Internet Draft M. Stiemerling Document: [-draft-ietf-midcom-semantics-01.txt-] {+draft-ietf-midcom-semantics-02.txt+} J. Quittek Expires: [-August-] {+November+} 2003 NEC Europe Ltd. Tom Taylor Nortel Networks [-February-] {+May+} 2003 MIDCOM Protocol Semantics [--] {++} Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC 2026. 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 Distribution of this document is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This memo specifies semantics for a Middlebox Communication (MIDCOM) protocol to be used by MIDCOM agents for interacting with middleboxes, such as firewalls and NATs. The semantics discussion does not include any specification of a concrete syntax or a transport protocol. However, a concrete protocol is expected to implement the specified semantics or - more probably - a superset of it. The MIDCOM protocol semantics is derived from the MIDCOM requirements, from the MIDCOM framework, and from working group {+decisions.+} Stiemerling, Quittek, Taylor [Page 1] Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 [-decisions.-] Table of Contents 1 Introduction ................................................. 2 1.1 Terminology ................................................ 3 1.2 Transaction Definition Template ............................ 4 2 Semantics Specification ...................................... 5 2.1 General Protocol Design .................................... 5 2.1.1 {+Protocol Transactions .................................... 5 2.1.2+} Session, Policy Rule, and Policy Rule Group .............. 6 [-2.1.2-] {+2.1.3+} Atomicity ................................................ 7 [-2.1.3-] {+2.1.4+} Access Control ........................................... [-7 2.1.4 Conformance ..............................................-] 8 2.1.5 Middlebox [-Capabilites ....................................-] {+Capabilities ...................................+} 8 {+2.1.6 Peer Identifiers ......................................... 9 2.1.7 Conformance .............................................. 9+} 2.2 Session Control Transactions ............................... [-8-] {+9+} 2.2.1 Session Establishment (SE) ............................... [-9-] {+10+} 2.2.2 Session Termination (ST) ................................. [-11-] {+12+} 2.2.3 Asynchronous Session Termination (AST) ................... 12 2.2.4 Session Termination by Interruption of Connection ........ [-12-] {+13+} 2.2.5 Session State Machine .................................... [-12-] {+13+} 2.3 Policy Rule Transactions ................................... 14 2.3.1 [-Overview .................................................-] {+Configuration Transactions ...............................+} 14 2.3.2 Establishing Policy Rules ................................ 15 2.3.3 Maintaining Policy Rules and Policy Rule Groups .......... 16 2.3.4 Address Tuples ........................................... 16 2.3.5 Address Parameter Constraints ............................ [-17-] {+18+} 2.3.6 Policy Reserve Rule (PRR) ................................ 19 2.3.7 Policy Enable Rule (PER) ................................. 22 2.3.8 Policy Rule Lifetime Change (RLC) ........................ [-26-] {+27+} 2.3.9 Policy Rule {+List (PRL) ................................... 29 2.3.10 Policy Rule+} Status (PRS) [-................................. 28 2.3.10-] {+................................ 30 2.3.11+} Asynchronous Policy Rule Deletion (ARD) ................. [-30 2.3.11-] {+32 2.3.12+} Policy Rule State Machine ............................... [-30-] {+32+} 2.4 Policy Rule Group Transactions ............................. [-32-] {+33+} 2.4.1 Overview ................................................. [-32-] {+34+} 2.4.2 Group Lifetime Change (GLC) .............................. [-33-] {+34+} 2.4.3 Group List (GL) .......................................... [-34-] {+36+} 2.4.4 Group Status (GS) ........................................ [-35-] {+37+} 3 Conformance Statements ....................................... [-36-] {+38+} 3.1 General Implementation Conformance ......................... [-37-] {+39+} 3.2 Middlebox Conformance ...................................... [-37-] {+39+} 3.3 Agent Conformance .......................................... [-38-] {+40+} 4 Transaction Usage Examples ................................... [-38-] {+40+} 4.1 Exploring Policy Rules and Policy Rule Groups .............. [-38-] {+40+} 4.2 Enabling a SIP-Signaled Call ............................... [-41-] {+44+} 5 Compliance with MIDCOM Requirements .......................... [-46-] {+49+} 5.1 Protocol Machinery Requirements ............................ [-46-] {+49+} 5.1.1 Authorized Association ................................... [-46-] {+49+} 5.1.2 Agent connects to Multiple Middleboxes ................... [-46-] {+49 5.1.3 Multiple Agents connect to same Middlebox ................ 50+} Stiemerling, Quittek, Taylor [Page 2] Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 [-5.1.3 Multiple Agents connect to same Middlebox ................ 47-] 5.1.4 Deterministic Behavior ................................... [-47-] {+50+} 5.1.5 Known and Stable State ................................... [-47-] {+50+} 5.1.6 Status Report ............................................ [-48-] {+51+} 5.1.7 Unsolicited Messages (Asynchronous Notifications) ........ [-48-] {+51+} 5.1.8 Mutual Authentication .................................... [-48-] {+51+} 5.1.9 Session Termination by any Party ......................... [-48-] {+51+} 5.1.10 Request Result .......................................... [-48-] {+51+} 5.1.11 Version Interworking .................................... [-49-] {+51+} 5.1.12 Deterministic Handling of Overlapping Rules ............. [-49-] {+52+} 5.2 Protocol Semantics Requirements ............................ [-49-] {+52+} 5.2.1 Extensible Syntax and Semantics .......................... [-49-] {+52+} 5.2.2 Policy Rules for Different Types of Middleboxes .......... [-49-] {+52+} 5.2.3 Ruleset Groups ........................................... [-49-] {+52+} 5.2.4 Policy Rule Lifetime Extension ........................... [-50-] {+52+} 5.2.5 Robust Failure Modes ..................................... [-50-] {+53+} 5.2.6 Failure Reasons .......................................... [-50-] {+53+} 5.2.7 Multiple Agents Manipulating Same Policy Rule ............ [-50-] {+53+} 5.2.8 Carrying Filtering Rules ................................. [-50-] {+53+} 5.2.9 Parity of Port Numbers ................................... [-50-] {+53+} 5.2.10 Consecutive Range of Port Numbers ....................... [-50-] {+53+} 5.2.11 Contradicting Overlapping Policy Rules .................. [-51-] {+54+} 5.3 Security Requirements ...................................... [-51-] {+54+} 5.3.1 Authentication, Confidentiality, Integrity ............... [-51-] {+54+} 5.3.2 Optional Confidentiality of Control Messages ............. [-51-] {+54+} 5.3.3 Operation across Un-trusted Domains ...................... [-51-] {+54+} 5.3.4 Mitigate Replay Attacks .................................. [-51-] {+54+} 6 Security Considerations ...................................... [-51-] {+54+} 7 Acknowledgements ............................................. [-52-] {+55+} 8 Open Issues .................................................. [-52-] {+55+} 9 Normative References ......................................... [-53-] {+56+} 10 Informative References ...................................... [-53-] {+56+} 11 Authors' Addresses .......................................... [-53-] {+56+} 12 Full Copyright Statement .................................... [-54-] {+57+} 1. Introduction The MIDCOM working group has defined a framework [MDC-FRM] for the middlebox communication [-as well as-] {+and+} a list of requirements [MDC-REQ]. The next step towards a MIDCOM protocol is the specification of protocol semantics that are constrained, but not [-complletely-] {+completely+} implied by the documents mentioned above. This memo suggests a semantics for the MIDCOM protocol. It is fully compliant with the requirements listed in [MDC-REQ] and with the working group's consensus on semantic issues. In conformance with the working group charter, the semantics description is targeted at packet filters and network address {+translators (NATs) and it supports applications that require dynamic+} Stiemerling, Quittek, Taylor [Page 3] Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 [-translators (NATs) and it supports applications that require dynamic-] configuration of these middleboxes. The semantics are defined in terms of transactions. Two basic types of transactions are used: request-reply transactions and notification transactions. For each transaction the semantics is specified by describing (1) the parameters of the transaction, (2) the processing (of request messages) at the middlebox, and (3) the state transitions at the middlebox caused by the request transactions or indicated by the notification transactions, respectively. The semantics can be implemented by any protocol that supports these two transaction types and that is sufficiently flexible concerning transaction parameters. Different implementations for different protocols might need to extend the semantics described below by adding further transactions and/or adding further parameters to {+transactions and/or splitting single transactions into a set of+} transactions. Regardless of such extensions, the semantics below provide [-the-] {+a+} minimum necessary subset of what must be implemented. The [-reminder-] {+remainder+} of this document is structured as follows. Section 2 describes the protocol semantics. It is structured in four subsections: - General Protocol Issues (Section 2.1) - Session Control (Section 2.2) - Policy Rules (Section 2.3) - Policy Rule Groups (Section 2.4) Section 3 contains conformance statements for MIDCOM protocol definitions and MIDCOM protocol implementations with respect to the semantics defined in Section 2. Section 4 gives two elaborated usage examples. Finally, Section 5 explains how the semantics meets the MIDCOM requirements. 1.1. Terminology The terminology in this memo follows the definitions given in the framework [MDC-FRM] and requirements [MDC-REQ] document. In addition the following terms are used: request transaction A request transaction consists of a request message transfer from the agent to the middlebox, [-procesing-] {+processing+} of the message at the middlebox, and a reply message transfer from the middlebox to the agent. A request transaction might cause a state transition at the middlebox. Stiemerling, Quittek, Taylor [Page 4] Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 configuration transaction A configuration transaction is a request transaction containing a request for state change in the middlebox. If accepted, it causes a state change at the middlebox. monitoring transaction A monitoring transaction is a request transaction containing a [-requests-] {+request+} for state information from the middlebox. It does not cause a state transition at the middlebox. notification transaction A notification transaction consists of an asynchronous message transfer from the middlebox [-and-] to the agent. The message indicates a state [-transistion-] {+transition+} at the middlebox. agent unique An agent unique value is unique in the context of the agent. This context includes all MIDCOM [-session-] {+sessions+} the agent participates in. An agent unique value is assigned by the agent. middlebox unique A middlebox unique value is unique in the context of the middlebox. This context includes all MIDCOM [-session-] {+sessions+} the middlebox participates in. A middlebox unique value is assigned by the middlebox. policy rule In general, a policy rule is "a basic building block of a policy-based system. It is the binding of a set of actions to a set of conditions - where the conditions are evaluated to determine whether the actions are performed." [RFC3198]. In the MIDCOM context the condition is a specification of a set of packets to which rules are applied. The set of actions always [-contain-] {+contains+} just a single element per rule, either action "reserve" or action "enable". policy reserve rule A policy rule containing a reserve action. The policy condition of this rule is always true. The action is the reservation of just an IP address or a combination of an IP address and a range of port numbers on neither, one, or both sides of the middlebox, depending on the latter's configuration. Stiemerling, Quittek, Taylor [Page 5] Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 policy enable rule A policy rule containing an enable action. The policy condition consists of a descriptor of one or more unidirectional or bidirectional {+packet+} flows, and the policy action enables packets belonging to this flow to traverse the middlebox. The descriptor identifies the protocol, the flow direction, the source and destination addresses, optionally with a range of port numbers. 1.2. Transaction Definition Template In the following sections, semantics of the MIDCOM protocol is specified per transaction. A transaction specification contains the following entries. (Parameter entries are only specified if applicable.) transaction-name A description name for this type of transaction. transaction-type The transaction type is either 'configuration', 'monitoring', or 'notification'. See Section 1.1. for a description of transaction types. transaction-compliance This entry contains either 'mandatory' or 'optional'. For details see Section 2.1.4. request-parameters This entry lists all parameters that are necessary for this request. A description for each parameter is given. reply-parameters (success) This entry lists all parameters that are sent back from the middlebox to the agent as positive response to the prior request. A description for each parameter is given. [-reply-parameters (failure) This entry lists all parameters that are sent back from the middlebox to the agent as-] {+failure reason All+} negative [-response to-] {+replies do just have two parameters, a request identifier identifying+} the [-prior request. A description for each parameter-] {+request on which the reply+} is [-given. notification parameters This entry lists all-] {+sent and a parameter indicating the failure reason. Since these+} parameters [-that-] are [-used by-] {+compulsory, they are not listed in+} the [-middlebox-] {+template. But the template contains a list of potential failure reasons that may be indicated by the second parameter. The list is not exclusive. A concrete protocol specification may extend the list. Stiemerling, Quittek, Taylor [Page 6] Internet-Draft MIDCOM Protocol Semantics May 2003 notification parameters This entry lists all parameters that are used by the middlebox+} to notify the agent about any asynchronous event. A description for each parameter is given. [-Stiemerling, Quittek, Taylor [Page 6] Internet-Draft MIDCOM Protocol Semantics February 2003-] semantics This entry describes the actual semantics of the transaction. Particularly, it describes the processing of the request [-by the middlebox. Each request-] message [-contains a parameter identifying the requesting agent, and each reply message and each notification message contains a parameter identifying the middlebox. These parameters are not explicitly listed in the description of-] {+by+} the [-individual transactions, because they are common to all of them-] {+middlebox,+} and [-not further referred to in the individual semantics descriptions. Also, they are not necessarily passed explicitly as parameters of the midcom protocol, but they might be provided-] {+middlebox state transitions caused+} by {+or causing+} the [-used underlying (secure) transport protocol.-] {+transaction, respectively.+} 2. Semantics Specification 2.1. General Protocol Design The semantics specification aims at a balance between proper support of applications that require dynamic configuration of middleboxes and simplicity of specification and implementation of the protocol. [-Two kinds-] {+Protocol interactions are structured into transactions. State+} of {+middleboxes is described by+} state [-transitions-] {+machines. The state machines are defined by states and state transitions. A single transaction+} may [-occur at the middlebox:-] {+cause or be caused by state transitions in more than one state machine, but per+} state {+machine there is no more than one transition per transaction. 2.1.1. Protocol Transactions State+} transitions are either initiated by a request {+message+} from the agent to the middlebox, or they are initiated by some other [-event.-] {+event at the middlebox.+} In the first [-case-] {+case,+} the middlebox informs the agent by sending a reply {+message+} on the actual state transition, in latter case the middlebox sends [-a-] {+an unsolicited asynchronous+} notification {+message+} to the agent. [-Requests-] {+Request+} and [-replies-] {+reply messages+} contain an agent unique request identifier that allows the agent to determine to which sent request a received reply corresponds. [-To allow both agents and middleboxes to maintain multiple sessions, every message contains information identifying its sender. In the actual protocol, this identifying information may be provided by a layer below the middlebox control application. It is not shown explicitly in the message descriptions provided below, but should be assumed as a semantic requirement. An analysis of-] {+An analysis of+} the requirements showed that [-three-] {+four+} kinds of transactions are required: {+-+} configuration transactions allowing the agent to request state transitions at the [-middlebox, monitoring transaction allowing the agent to request state information from the middlebox, and-] {+middlebox -+} notification transactions allowing the middlebox to inform the agent about state transitions not requested by the [-agent.-] {+agent+} Stiemerling, Quittek, Taylor [Page 7] Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 [-2.1.1.-] {+- monitoring transaction allowing the agent to request state information from the middlebox - convenience transactions combining a set of configuration transactions Configuration transactions and notification transactions provide the basic MIDCOM protocol functionality. They are related to middlebox state transactions and they concern estalishment and termination of MIDCOM sessions and of policy rules. Monitoring transactions are not related to middlebox state transitions. They are usd by agents for exploring number, status and properties of policy rules established at the middlebox. Convenience transaction simplify MIDCOM sessions by combining a set of configuration transactions into a single one. They are not necessary for MIDCOM protocol operation. As specified in detail in Section 3, configuration transactions and notification transactions are mandatory. They must be implemented by a compliant middlebox. The monitoring and onvenience transactions are optional. 2.1.2.+} Session, Policy Rule, and Policy Rule Group All transactions can further be grouped into transactions concerning sessions, transactions concerning policy rules, and transactions concerning policy rule groups. Policy rule groups can be used to indicate relationships between policy rules and to simplify transactions on a set of policy rules by using a single one per group instead of one per policy rule. Sessions and policy rules at the middlebox are stateful. Their states are independent of each other and their state machines (one per session and one per policy rule) can be separated. [-For policy-] {+Policy+} rule [-group-] {+groups+} are also stateful, [-by-] {+but+} the middlebox does not need to maintain state for policy rule groups, because the semantics [-was-] {+were+} chosen such that the policy rule group state is implicitly defined by the state of all policy rules belonging to the group (see Section 2.4). The separation of session state and policy rule state simplifies the specification of the semantics as well as a protocol implementation. Therefore, the semantics specification is structured accordingly and we use two separated state machines to illustrate the semantics. Please note, that state machines of concrete protocol designs and implementations will most probably be more complex than the state machines presented here. However, the protocol state machines are expected to be a superset of the [-semantic-] {+semantics+} state machines in this {+Stiemerling, Quittek, Taylor [Page 8] Internet-Draft MIDCOM Protocol Semantics May 2003+} document. [-2.1.2.-] {+2.1.3.+} Atomicity All request transactions are atomic with respect to each other. This means that processing of a request at the middlebox is never interrupted by another arriving or already queued request. This particularly applies when the middlebox concurrently receives requests originating in different sessions. However, asynchronous notification transactions may interrupt [-and-] {+and/or+} terminate processing of a request at any time. All request transactions are atomic from the point of view of the agent. Processing of a request does not start before the complete request arrives at the middlebox. No intermediate state is stable at the middlebox and no intermediate state is reported to any agent. The number of transactions specified in this document is rather small. Again for simplicity we reduced it close to a minimal set that still meets the requirements. For a real implementation of the protocol, it might be required to split some of the transactions specified below into two or more transactions of the respective protocol. Reasons for this might be constraints of the particular [-Stiemerling, Quittek, Taylor [Page 8] Internet-Draft MIDCOM Protocol Semantics February 2003-] protocol or the desire for more flexibility. In general this should not be a problem. However, it should be considered that this might change atomicity of the affected transactions. [-2.1.3.-] {+2.1.4.+} Access Control Access to policy rules and policy rule groups is based on ownership. When a policy rule is created, a middlebox unique identifier is generated for identifying it in further transactions. Beyond the identifier, each policy rule has an owner. The owner is the authenticated agent that established the policy rule. The middlebox uses the owner attribute of a policy rule [-or group-] for controlling access to it: each time an authenticated agent requests to modify an existing policy rule, the middlebox determines the owner of the policy rule and checks if the requesting agent is authorized to perform transactions on the owning agent's policy rules. {+All policy rules belonging to the same policy rule group must have the same owner. Therefore, authenticated agents either have access to all members of a policy rule group, or to none of them.+} The middlebox may be configured to allow specific authenticated agents to access and modify policy rules with certain specific owners. Certainly, a reasonable default configuration would be that each agent can access its own policy rules. Also, it might be a good {+Stiemerling, Quittek, Taylor [Page 9] Internet-Draft MIDCOM Protocol Semantics May 2003+} idea, to have an agent identity configured to act as administrator being allowed to modify all policy rules owned by any agent. Anyway, the configuration of authorization is not subject of the MIDCOM protocol semantics. [-2.1.4. Conformance The MIDCOM requirements in [MDC-REQ] demand certain capabilities of-] {+2.1.5. Middlebox Capabilities For several reasons it is useful that the agent learns at session establishment about particular capabilities of the middlebox. Therefore, the session establishment procedure described in Section 2.2.1 includes a transfer of capability information from the middlebox to the agent. The list of covered middlebox capabilities includes - type of the middlebox for example: FW, NAT, NAPT, NAT-PT, twice-NAT or combination of those - internal IP address wildcard support - external IP address wildcard support - port wildcard support - supported IP version(s) for internal network: IPv4, IPv6, or both - supported IP version(s) for external network: IPv4, IPv6, or both - list of supported optional MIDCOM protocol transactions - policy rule persistency: persistent or non-persistent A rule is persistent when the middlebox can save the rule to a non-volatile memory, e.g. a hard disk or flash memory. - maximum remaining lifetime of a policy rule or policy rule group The list of middlebox capabilities may be extended by a concrete protocol specification by further information that is useful for the agent. 2.1.6. Peer Identifiers In order to allow both agents and middleboxes to maintain multiple sessions each request message contains a parameter identifying the requesting agent, and each reply message and each notification message contains a parameter identifying the middlebox. These parameters are not explicitly listed in the description of the individual transactions, because they are common to all of them and not further referred to in the individual semantics descriptions. Also, they are not necessarily passed explicitly as parameters of the midcom protocol, but they might be provided by the used underlying (secure) transport protocol. Stiemerling, Quittek, Taylor [Page 10] Internet-Draft MIDCOM Protocol Semantics May 2003 2.1.7. Conformance The MIDCOM requirements in [MDC-REQ] demand certain capabilities of+} the MIDCOM protocol, which are met by the set of transactions specified below. However, an actual implementation of a middlebox may support only a subset of these transactions. Support limitation may be different for different authenticated agents. At session establishment, the middlebox informs the authenticated agent by capability exchange, which transactions the agent is authorized to perform. Some transactions need to be offered to every authenticated agent. Each transaction definition below has a conformance entry which contains either 'mandatory' or 'optional'. A mandatory transaction needs to be implemented by every middlebox offering MIDCOM service. A mandatory request transaction must be offered to each of the authenticated agents. An optional transaction does not necessarily need to be implemented by a middlebox. An implemented optional request transaction does not necessarily need to be offered to every authenticated agent. Whether or not an agent is allowed to use an optional request transaction is determined by the middlebox's authorization procedure which is not further specified by this [-Stiemerling, Quittek, Taylor [Page 9] Internet-Draft MIDCOM Protocol Semantics February 2003-] document. [-2.1.5. Middlebox Capabilites Editor's note: to be done. (policy rule persistency...)-] 2.2. Session Control Transactions Before any transaction on policy rules or policy rule groups is possible, a valid MIDCOM session must be established. A MIDCOM session is an {+authenticated and+} authorized association between agent and middlebox. Sessions are initiated by agents and can be terminated by either the agent or the middlebox. Both agent and middlebox may participate in several sessions (with different entities) at the same time. For distinguishing different sessions each party uses local session identifiers. Session control is supported by three transactions: - Session Establishment (SE) - Session Termination (ST) - Asynchronous Session Termination (AST) The first two are [-request-] {+configuration+} transactions initiated by the agent, the last one is a notification transaction initiated by the middlebox. {+Stiemerling, Quittek, Taylor [Page 11] Internet-Draft MIDCOM Protocol Semantics May 2003+} 2.2.1. Session Establishment (SE) transaction-name: session establishment transaction-type: configuration transaction-compliance: mandatory request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. - version: the version of the MIDCOM protocol - middlebox authentication challenge (mc): an authentication challenge token for authentication of the middlebox. As seen below, this is present only in the first iteration of the request. [-Stiemerling, Quittek, Taylor [Page 10] Internet-Draft MIDCOM Protocol Semantics February 2003-] - agent authentication (aa): an authentication token to authenticate the agent to the middlebox. As seen below, this is updated in the second iteration of the request with material responding to the middlebox challenge. [-- encryption method: an identifier of an encryption method. Also 'no encryption' may be specified.-] reply-parameters (success): - request identifier: an identifier matching the identifier request. - middlebox authentication (ma): an authentication token to authenticate the middlebox to the agent. - agent challenge token (ac): an authentication challenge token for the agent authentication. - middlebox capabilities: a [-parameter set-] {+list+} describing the middlebox's capabilities. [-The set includes - type of the middlebox for example: FW, NAT, NATFW, NAPT, NAPTFW, NAT-PT, NAT-PTFW, ... - IP address wildcard support - port wildcard support - supported IP version(s) for internal network: IPv4, IPv6, or both - supported IP version(s)-] {+See Section 2.1.6.+} for [-external network: IPv4, IPv6, or both - list of supported optional MIDCOM protocol transactions - policy rule persistency: persistent or not persistent - maximum remaining lifetime of a policy rule or policy rule group reply-parameters (failure): - request identifier: an identifier matching-] the [-identifier-] {+list+} of [-the request. --] {+middlebox capabilities.+} failure reason: [-the reason why the session establishment transaction failed. The list of possible reasons includes but is not restricted to:-] - authentication failed - no authorization - protocol version of agent and middlebox do not match - [-encryption method not supported --] lack of resources semantics: [-Stiemerling, Quittek, Taylor [Page 11] Internet-Draft MIDCOM Protocol Semantics February 2003-] This session establishment transaction is used to establish a MIDCOM session. For mutual authentication of both parties two {+Stiemerling, Quittek, Taylor [Page 12] Internet-Draft MIDCOM Protocol Semantics May 2003+} subsequent session establishment transactions are required as shown in Figure 1. agent middlebox | session establishment request | | (with middlebox challenge mc) | {+CLOSED+} |-------------------------------------------->| | | | successful reply (with middlebox | | authentication ma and agent challenge ac) | |<--------------------------------------------| | | {+NOAUTH+} | session establishment request | | (with agent authentication aa) | |-------------------------------------------->| | | | successful reply | |<--------------------------------------------| | | {+OPEN | |+} Figure 1: Mutual authentication of agent and middlebox Session establishment may be simplified by using only a single transaction. In this case server challenge and agent challenge are omitted by the sender or ignored by the receiver, and authentication must be provided by other means, for example by TLS [RFC2246] or IPSEC [RFC2402][RFC2406]. The middlebox checks with its policy decision point if the requesting agent is authorized to open a MIDCOM session. If not a negative reply with 'no authorization' as failure reason is generated by the middlebox. If authentication and authorization are successful, the session is established and the agent may start with requesting transactions on policy rules and policy rule groups. Part of the successful reply is an indication of the middlebox's capabilities. Editor's note: The list of capabilities to be included needs to be further elaborated, taking into account how the agent is expected to use this information. [-The agent specifies an encryption method for the session but has the option of not using encryption. The middlebox can accept this suggestion or reject it. In case of rejection, the-] {+2.2.2. Session Termination (ST) transaction-name:+} session [-establishment fails and an appropriate failure reason is indicated by the middlebox in the reply message. Then the agent may try-] {+termination transaction-type: configuration+} Stiemerling, Quittek, Taylor [Page [-12]-] {+13]+} Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 [-session setup again with a different encryption method. 2.2.2. Session Termination (ST) transaction-name: session termination transaction-type: configuration-] transaction-compliance: mandatory request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. reply-parameters (success only): - request identifier: an identifier matching the identifier of the request. semantics: This transaction is used to close the MIDCOM session on behalf of the agent. After session termination the middlebox keeps all established policy rules until their lifetime expires or until an event occurs which causes the middlebox to terminate them. The middlebox always generates a successful reply. After sending the reply, the middlebox will not send any further messages to the agent within the current session. It also will not process any further request within this session, which it has received while it was processing the session termination request, or which it receives later. 2.2.3. Asynchronous Session Termination (AST) transaction-name: asynchronous session termination transaction-type: notification transaction-compliance: mandatory notification-parameters: - termination reason: The reason why the session is terminated without any request from the agent. semantics: [-Stiemerling, Quittek, Taylor [Page 13] Internet-Draft MIDCOM Protocol Semantics February 2003-] The middlebox may decide at any point in time to terminate a MIDCOM session. Before terminating the actual session the [-middle box-] {+middlebox+} generates this notification transaction. After sending the notification, the middlebox will not process any further request by the agent, even if it is already queued at the middlebox. After session termination the middlebox keeps all established {+Stiemerling, Quittek, Taylor [Page 14] Internet-Draft MIDCOM Protocol Semantics May 2003+} policy rules until their lifetime expires or until an event occurs on which the middlebox terminates them. 2.2.4. Session Termination by Interruption of Connection If a MIDCOM session is based on an underlying network connection, then the session can also be terminated by an interruption of this connection. If the middlebox detects this, it immediately terminates the session. The effect on established policy rules is the same as for the Asynchronous Session Termination. 2.2.5. Session State Machine A state machine illustrating the semantics of the session transactions is shown in Figure 2. The used transaction abbreviations can be found in the headings of the particular transaction section. All sessions start in state CLOSED. A successful SE transaction can cause a state transition to state OPEN, if mutual authentication is already provided by other means. Otherwise, it causes a transition to state NOAUTH. From this state a failed second SE transaction returns to state CLOSED. A successful SE transaction causes a transition to state OPEN. At any time an AST transaction or a connection failure may occur causing a transition to state CLOSED. A successful ST transaction from either NOAUTH or OPEN also causes a return to CLOSED. [-Stiemerling, Quittek, Taylor [Page 14] Internet-Draft MIDCOM Protocol Semantics February 2003-] mc = middlebox challenge SE/failure ma = middlebox authentication +-------+ ac = agent challenge | v aa = agent authentication +----------+ | CLOSED |----------------+ +----------+ | SE(mc!=0)/ | ^ ^ | success(ma,ac) SE(mc=0, | | | AST | aa=OK)/ | | | SE/failure v success | | | ST/success +----------+ | | +------------| NOAUTH | | | +----------+ | | AST | SE(mc=0, v | ST/success | aa=OK)/ +----------+ | success | OPEN |<---------------+ +----------+ Figure 2: Session State Machine {+Stiemerling, Quittek, Taylor [Page 15] Internet-Draft MIDCOM Protocol Semantics May 2003+} 2.3. Policy Rule Transactions This section describes the semantics for transactions on policy rules. The following transactions are specified: - Policy Reserve Rule (PRR) - Policy Enable Rule (PER) - Policy Rule Lifetime Change (RLC) - Policy Rule {+List (PRL) - Policy Rule+} Status (PRS) - Asynchronous Policy Rule Deletion (ARD) The first [-four-] {+three transactions (PRR, PER, PLC)+} are [-request-] {+configuration+} transactions initiated by the [-agent,-] {+agent. The fourth and fifth (PRL, PRS) are a monitoring transactions. And+} the last one {+(ARD)+} is a notification [-transaction initiated by the middlebox.-] {+transaction.+} The [-status information transaction (PRS) does-] {+PRL and PRS and transactions do+} not have any effect on the policy rule state machine. Before any transaction can start, a valid MIDCOM session must be established. 2.3.1. [-Overview-] {+Configuration Transactions+} Policy Rule transactions PER and RLC constitute the core of the MIDCOM protocol. Both are mandatory and they serve for - configuring NAT bindings (PER) - configuring firewall pinholes (PER) - extending the lifetime of established policy rules (RLC) [-Stiemerling, Quittek, Taylor [Page 15] Internet-Draft MIDCOM Protocol Semantics February 2003-] - deleting policy rules (RLC) In some cases it is required to know in advance which IP address (and port number) would be chosen by NAT in a PER transaction. This information is required before sufficient information for performing a complete PER transaction is available (see example in Section 4.2). For supporting such cases, the core transactions are extended by the Policy Reserve Rule (PRR) transaction serving for - reserving addresses and port numbers at NATs (PRR) [-A policy rule contains either-] {+2.3.2. Establishing Policy Rules Both PRR and PER establish+} a [-reserve-] {+policy rule. The+} action [-(established-] {+within the rule is 'reserve' if set+} by PRR [-transaction) or an enable action (established-] {+and 'enable' if set+} by [-PER transaction). 2.3.2. Establishing Policy Rules-] {+PER.+} The Policy Reserve Rule (PRR) transaction is used to establish an address reservation on neither, one, or both sides of the middlebox, depending on the latter's configuration. The transaction returns the {+Stiemerling, Quittek, Taylor [Page 16] Internet-Draft MIDCOM Protocol Semantics May 2003+} reserved IP addresses and the optional ranges of port numbers to the agent. No address binding or pinhole configuration is performed at the middlebox. Packet processing at the middlebox remains unchanged. On pure firewalls, the PRR transaction is successfully [-installed-] {+processed+} without any reservation, but the state transition of the midcom protocol engine is exactly the same as on NATs. On a traditional NAT, just an external address is reserved; on a twice-NAT, an internal and an external address is reserved. In both cases the reservation concerns either an IP address {+only+} or a combination of an IP address with a range of port numbers. The Policy Enable Rule (PER) transaction is used to establish a policy rule that has an effect on packet [-treatment-] {+processing+} at the middlebox. Depending on its input parameters, it may make use of the reservation established by a PRR transaction, or create a new rule from scratch. On a NAT, the enable action is interpreted as as bind action establishing bindings between internal and external addresses. At a firewall, the enable action is interpreted as one or more allow actions configuring pinholes. The number of allow actions depends on the parameters of the request and the implementation of the firewall. {+On a combined NAT/firewall, the enable action is interpreted as a combination of bind and allow actions.+} The PRR transaction and the PER transaction are described in [-more detail in Sections 2.3.6. and 2.3.7. below. Stiemerling, Quittek, Taylor [Page 16] Internet-Draft MIDCOM Protocol Semantics February 2003-] {+more detail in Sections 2.3.6. and 2.3.7. below.+} 2.3.3. Maintaining Policy Rules and Policy Rule Groups Each policy rule has a middlebox unique identifier. Each policy rule has an owner. Access control to the policy rule is based on ownership (see section [-2.1.3).-] {+2.1.4).+} Ownership of a policy rule does not change during lifetime of the policy rule. Each policy rule has its individual lifetime. If the policy rule lifetime expires, the policy rule will be deleted at the middlebox. {+Typically, the middlebox indicates deletion of a policy rule by an ARD transaction.+} A policy rule lifetime change (RLC) transaction may extend the lifetime of the policy rule up to the limit specified by the middlebox at session setup. Also a RLC transaction may be used for {+shortening a policy rule's lifetime or+} deleting a policy rule by requesting a lifetime of zero. (Please note that policy rule lifetimes may also be modified by the group lifetime change (GLC) transaction). {+Stiemerling, Quittek, Taylor [Page 17] Internet-Draft MIDCOM Protocol Semantics May 2003+} Each policy rule is member of exactly one policy rule group. Group membership does not change during the lifetime of a policy rule. Selecting the group is part of the transaction establishing the policy rule. This transaction implicitly creates a new group if the agent does not specify [-a group of which the new policy rule should become a member.-] {+one.+} The new group identifier is chosen by the middlebox. New members are added to a group, if the [-agents requests membership of-] {+agent's request designates+} an already existing group. A group only exists as long as it has member policy rules. As soon as all policies belonging to the group [-reached-] {+reach+} the end of their lifetimes, the group does not exist anymore. Agents can explore the properties and status of all policy rules they are allowed to access by using the Policy Rule Status [-(PRS).-] {+(PRS) transaction.+} 2.3.4. Address Tuples Request and reply messages of the PRR, PER, and PRS transactions contain address specifications for IP and transport addresses. These parameters include - IP version - IP address - {+IP address prefix length -+} transport protocol - port number - port parity - port range We refer to the set of these parameters as an address tuple. An address tuple specifies either a communication endpoint at an internal or external device or allocated addresses at the middlebox. In this document, we distinguish four kinds of address tuples as shown in Figure 3. [-Stiemerling, Quittek, Taylor [Page 17] Internet-Draft MIDCOM Protocol Semantics February 2003-] +----------+ +----------+ | internal | A0 A1 +-----------+ A2 A3 | external | | endpoint +----------+ middlebox +----------+ endpoint | +----------+ +-----------+ +----------+ Figure 3: Address tuples A0 - A3 - A0 - internal endpoint: address tuple A0 specifies a communication endpoint of a devices within the - with respect to the middlebox - internal network. {+Stiemerling, Quittek, Taylor [Page 18] Internet-Draft MIDCOM Protocol Semantics May 2003+} - A1 - middlebox inside address: address tuple A1 specifies a virtual communication endpoint at the middlebox within the internal network. {+A1 is the destination address for packets passing from the internal endpoint to the middlebox, and is the source for packets passing from the middlebox to the internal endpoint.+} - A2 - middlebox outside address: address tuple A2 specifies a virtual communication endpoint at the middlebox within the external network. {+A2 is the destination address for packets passing from the external endpoint to the middlebox, and is the source for packets passing from the middlebox to the external endpoint.+} - [-A0-] {+A3+} - external endpoint: address tuple A3 specifies a communication endpoint of a devices within the - with respect to the middlebox - external network. For a firewall, the inside and outside endpoints are identical to the corresponding external or internal endpoints, repectively. In this case [-A0=A2-] {+the installed policy rule sets the same value in A2 as in A0 (A0=A2),+} and [-A1=A3.-] {+sets the same value in A1 as in A3 (A1=A3).+} For a traditional NAT, [-A0-] {+A2+} is {+given a value+} different from [-A2,-] {+that of A0,+} but the NAT binds them. As for the firewall, [-A1=A3-] {+so+} at a traditional [-NAT.-] {+NAT: A1 has the same value as A3.+} For a twice-NAT there are two bindings of address tuples: {+A1 and A2 are both assigned values by the NAT.+} The middlebox outside address A2 is bound to the internal endpoint A0 and the middlebox inside address A1 is bound to the external endpoint A3. 2.3.5. Address Parameter Constraints For transaction parameters belonging to an address tuple some constraints exist which are common for all messages using them. Therefore, these constraints are summarized in the following and not repeated again when describing the parameters in the transaction descriptions. The IP version parameter has either the value 'IPv4' or 'IPv6'. In a policy rule, the value of the IP version parameter must be the same for address tuples A0 and A1, and it must be the same for A2 and A3. The value of the IP address parameter must conform with the specified IP version. The [-specified-] IP address [-cannot-] {+of an address tuple may+} be wildcarded. {+Whether IP address wildcarding is allowed or in which range it is allowed+} Stiemerling, Quittek, Taylor [Page [-18]-] {+19]+} Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 {+depends on the local policy of the middlebox, see also section 6 "Security Considerations". Wildcarding is specified by the IP address prefix length parameter of an address tuple. In line with the common use of a prefix length, this parameter indicates the number of high significant bits of the IP address that are fixed, while the remaining low significant bits of the IP address are wildcarded.+} The value of the transport protocol parameter can have one of the following values: 'TCP', 'UDP', 'ANY'. If the transport protocol parameter has the value 'ANY', then the values of the parameters port number, port range, and port parity are irrelevant. In a policy rule the value of the transport protocol parameter must be the same for all address tuples A0, A1, A2, and A3. The value of the port number parameter is either zero or a positive integer. A positive integer specifies a concrete UDP or TCP port number. The value zero specifies port wildcarding for the protocol specified by the transport protocol parameter. If the port number parameter has the value zero, then the value of the port range parameter is irrelevant. Depending on the value of the transport protocol parameter, this parameter may truly refer to ports, or may refer to an equivalent concept. The port parity parameter is diffently used in the context of policy reserve rules (PRR) and policy enable rules (PER). In the context of a PRR, the value of [-thei-] {+the+} parameter may be 'odd', 'even', or 'any'. It specifies the parity of the first (lowest) reserved port number. In the context of a PER, the port parity parameter indicates to the middlebox, whether or not port numbers allocated at the middlebox should have the same parity as the corresponding internal or external port numbers, respectively. In this context, the parameter has either the value 'same' or 'any'. If it has the value 'same', then the parity of the port number of A0 must be the same as the parity of the port number of A2, and the parity of the port number of A1 must be the same as the parity of the port number of A3. If the port parity parameter has the value 'any', then there are no [-contraints-] {+constraints+} on the parity of any port number. The port range parameter specifies a number of consecutive port numbers. Its value is a positive integer. Together with the port number parameter this parameter defines a set of consecutive port numbers starting with the port number specified by the port number parameter as the lowest port number and having as many elements as specified by the port range parameter. A value of one specifies just a single port number. The port range parameter must have the same value for each address tuple A0, A1, A2, and A3. A single policy rule P containing a port range value greater than one {+Stiemerling, Quittek, Taylor [Page 20] Internet-Draft MIDCOM Protocol Semantics May 2003+} is equivalent to a set of policy rules containing a number n of policies P_1, P_2, ..., P_n that equals the value of the port range parameter. All policy rules P_1, P_2, ..., P_n have a port range parameter value of one. Policy rule P_1 contains a set of address tuples A0_1, A1_1, A2_1, and A3_1, that each contain the first port number of the respective address tuples in P; policy rule P_2 contains a set of address tuples A0_2, A1_2, A2_2, and A3_2, that each contain the second port number of the respective address tuples [-Stiemerling, Quittek, Taylor [Page 19] Internet-Draft MIDCOM Protocol Semantics February 2003-] in P; and so on. 2.3.6. Policy Reserve Rule (PRR) transaction-name: policy reserve rule transaction-type: configuration transaction-compliance: mandatory request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. - group identifier: a reference to the group of which the policy reserve rule should be a member. {+As indicated in Section 2.3.3., if this value is not supplied, the middlebox assigns a new group for this policy reserve rule. - mode: the requested NAT mode of the middlebox. Allowed values are 'traditional' or 'twice'.+} - internal IP version: requested IP version at the inside of the middlebox, see Section 2.3.5. - external IP version: requested IP version at the outside of the middlebox, see Section 2.3.5. - transport protocol: see section 2.3.5. - port range: the number of consecutive port numbers to be reserved, see Section 2.3.5. - port parity: the requested parity of the first (lowest) port number to be reserved, Allowed values of this parameter are 'odd', 'even', and 'any'. See also Section 2.3.5. - policy rule lifetime: a lifetime proposal to the middlebox for the requested policy rule. {+Stiemerling, Quittek, Taylor [Page 21] Internet-Draft MIDCOM Protocol Semantics May 2003+} reply-parameters (success): - request identifier: an identifier matching the identifier of the request. - policy rule identifier: a middlebox unique policy rule identifier. It is assigned by the middlebox and used as policy rule handle in further policy rule transactions, particularly to refer to the policy reserve rule in a subsequent PER transaction. - group identifier: a reference to the group of which the policy reserve rule is a member. [-Stiemerling, Quittek, Taylor [Page 20] Internet-Draft MIDCOM Protocol Semantics February 2003-] - reserved inside IP address: The reserved IPv4 or IPv6 address on the internal side of the middlebox. For an outbound flow, this will be the destination to which the internal endpoint sends its packets (A1 in Figure 3). For an inbound flow, this will be the apparent source address of the packets as forwarded to the internal endpoint (A0 in Figure 3). The middlebox reserves and reports an internal address only in the case where twice-NAT is in effect. Otherwise, [-the-] {+an empty+} value [-of 0.0.0.0 (IPv4) or :: (IPv6)-] {+for the addresses+} indicates that no internal reservation was made. See also Section 2.3.5. - reserved inside port number: see section 2.3.5. - reserved outside IP address: The reserved IPv4 or IPv6 address on the external side of the middlebox. For an inbound flow, this will be the destination to which the external endpoint sends its packets (A2 in Figure 4). For an outbound flow, this will be the apparent source address of the packets as forwarded to the external endpoint(A3 in Figure 3). If the middlebox is configured as a pure firewall, [-the-] {+an empty+} value [-of this reply parameter is of 0.0.0.0 (IPv4) or :: (IPv6) indicating-] {+for the addresses indicates+} that no external reservation was made. See also Section 2.3.5. - reserved outside port number: see section 2.3.5. - policy rule lifetime: the policy rule lifetime granted by the middlebox, after which the reservation will be revoked if it has not been replaced already by a policy enable rule in a PER transaction. [-reply-parameters (failure): - an identifier matching the identifier of the request. --] failure reason: [-the reason why the reserve request was rejected. The list of possible reasons includes but is not restricted to:-] - agent not authorized for this transaction - agent not authorized for adding members to this group - [-no such group --] lack of IP addresses - lack of port numbers - lack of resources semantics: {+Stiemerling, Quittek, Taylor [Page 22] Internet-Draft MIDCOM Protocol Semantics May 2003+} The agent can use this transaction type to reserve an IP address or a combination of IP address, transport type, port number and port range at neither, one, or both sides of the middlebox as required to support the enabling of a flow. Typically the PRR will be used in scenarios where it is required to perform such a [-Stiemerling, Quittek, Taylor [Page 21] Internet-Draft MIDCOM Protocol Semantics February 2003-] reservation before sufficient parameters for a complete policy enable rule transaction are available. See section 4.2 for an example. When receiving the request, the middlebox determines how many address (and port) reservations are required based on its configuration. If it provides only packet filter services, it does not perform any reservation and just returns empty values for the reserved inside and outside IP addresses and port numbers. If it is configured for twice-NAT , it reserves both inside and outside IP adresses (and an optional range of port numbers) and returns them. Otherwise, it reserves and returns an outside IP address (and an optional range of port numbers) and retuns empty values for the reserved inside address and port range. If there is a lack of resources, such as avaliable IP addresses, port numbers, or storage for further policy rules, then the reservation fails and an appropriate failure reply is generated. If a non-existing policy rule group was specified, or if an existing policy rule group was specified that is not owned by the requesting agent, then no new policy rule is established and an appropriate failure reply is generated. In case of success, this transaction creates a new policy reserve rule. If [-the specified-] {+an already existing policy rule+} group [-exists already,-] {+is specified,+} then the new policy rule becomes a member of it. If no policy group is specified a new group is created with the new policy rule as its only member. The middlebox generates a middlebox unique identifier for the new policy rule. The owner of the new policy rule is the authenticated agent that sent the request. The middlebox chooses a lifetime value that is greater than zero and less than or equal to the minimum of the requested value and the maximum lifetime specified by the middlebox at [-session startup, i.e.: 0 <= lt_granted <= MINIMUM(lt_requested, lt_maximum) whereas: - lt_granted is-] {+session startup, i.e.: 0 <= lt_granted <= MINIMUM(lt_requested, lt_maximum) whereas: - lt_granted is the actually granted lifetime by the middlebox - lt_requested is the requested lifetime of the agent - lt_maximum is the maximum liftime specified at session setup The middelbox always reserves a middlebox external address tuple (A2) due to a PRR request. In a special case of a combined twice-NAT/NAT Stiemerling, Quittek, Taylor [Page 23] Internet-Draft MIDCOM Protocol Semantics May 2003 middlebox the agent can request only NAT service or twice-NAT service by choosing the mode 'traditional' or 'twice' respectively. An agent that does not have any preference chooses 'twice'. The 'traditional' value should only be used in order to select traditional NAT service at middleboxes offering both traditional NAT and twice NAT. In+} the [-actually granted lifetime by-] {+'twice' case+} the {+combined twice-NAT/NAT+} middlebox [-- lt_requested is-] {+reserves A2 and A1,+} the [-requested lifetime-] {+'traditional' case results in a reservation+} of [-the-] {+A2 only. An+} agent [-- lt_maximum is-] {+must always use+} the [-maximum liftime specified at session setup-] {+PRR transaction for choosing NAT only or twice- NAT service in the special case of a combined twice-NAT/NAT middlebox. A firewall middlebox ignores this parameter.+} If the protocol identifier is [-'IP',-] {+'ANY',+} then the middlebox reserves available inside and/or outside IP address(es) only. The reserved address(es) are returned to the agent. In this case the request- parameters port range and port parity as well as reply-parameters inside port number and outside port number are irrelevant. If the protocol identifier is 'UDP' or 'TCP', then a combination of an IP address and a consecutive sequence of port numbers, starting [-Stiemerling, Quittek, Taylor [Page 22] Internet-Draft MIDCOM Protocol Semantics February 2003-] with the specified parity, is reserved, on neither, one, or both sides of the middlebox as appropriate. The IP address(es) and the first (lowest) reserved port number(s) of the consecutive sequence are returned to the agent. (This also applies to other protocols supporting ports or the equivalent.) 2.3.7. Policy Enable Rule (PER) transaction-name: policy enable rule transaction-type: configuration transaction-compliance: mandatory request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. - [-group identifier: a reference to the group of which the policy enable rule should be a member. --] policy reserve rule identifier: a reference to an already existing policy reserve rule created by a PRR transaction. The reference may be empty, in which case the middlebox must assign any necessary addresses and port numbers within this PER transaction. If it is not empty, then the following request parameters are irrelevant: {+group identifier,+} transport protocol, port range, port parity, internal IP version, external IP version. - {+group identifier: a reference to the group of which the policy enable rule should be a member. As indicated in Section 2.3.3., Stiemerling, Quittek, Taylor [Page 24] Internet-Draft MIDCOM Protocol Semantics May 2003 if this value is not supplied, the middlebox assigns a new group for this policy reserve rule. -+} transport protocol: see section 2.3.5. - port range: the number of consecutive port numbers to be reserved, see Section 2.3.5. - port parity: the requested parity of the port number(s) to be mapped. Allowed values of this parameter are 'same' and 'any'. See also Section 2.3.5. - direction of flow: this parameter specifies the direction of enabled communication, either 'inbound', 'outbound', or 'bi- directional'. - internal IP version: requested IP version at the inside of the middlebox, see Section 2.3.5. - internal IP address: the IP address of the internal communication endpoint (A0 in Fig. 3), see Section 2.3.5. [-Stiemerling, Quittek, Taylor [Page 23] Internet-Draft MIDCOM Protocol Semantics February 2003-] - internal port number: the port number of the internal communication endpoint (A0 in Fig. 3), see Section 2.3.5. - external IP version: requested IP version at the outside of the middlebox, see Section 2.3.5. - external IP address: the IP address of the external communication endpoint (A3 in Fig. 3), see Section 2.3.5. - external port number: the port number of the external communication endpoint (A3 in Fig. 4), see Section 2.3.5. - policy rule lifetime: a lifetime proposal to the middlebox for the requested policy rule. reply-parameters (success): - request identifier: an identifier matching the identifier of the request. - policy rule identifier: a middlebox unique policy rule identifier. It is assigned by the middlebox and used as policy rule handle in further policy rule transactions. If a [-reserved-] policy {+reserve+} rule identifier was provided in the request, then the returned policy rule identifier has the same value. - group identifier: a reference to the group of which the policy enable rule is a member. {+If a policy reserve rule identifier was Stiemerling, Quittek, Taylor [Page 25] Internet-Draft MIDCOM Protocol Semantics May 2003 provided in the request, then this parameter identifies the group, of which the policy reserve rule was a member.+} - inside IP address: the IP address provided at the inside of the middlebox (A1 in Fig. 3). In case of a twice-NAT, this parameter will be an internal IP address reserved at the inside of the middlebox. In all other cases, this reply-parameter will be identical with the external IP address passed with the request. If the policy reserve rule identifier parameter was supplied in the request and if the respective PRR transaction reserved an inside IP address, then the inside IP address provided in the PER response will be the identical value to that returned by the response to the PRR request. See also Section 2.3.5. - inside port number: the internal port number provided at the inside of the middlebox (A1 in Fig. 3), see also Section 2.3.5. - outside IP address: the external IP address provided at the outside of the middlebox (A2 in Fig. 4). In case of a pure firewall, this parameter will be identical with the internal IP address passed with the request. In all other cases, this reply- parameter will be an external IP address reserved at the outside of the middlebox. See also Section 2.3.5. [-Stiemerling, Quittek, Taylor [Page 24] Internet-Draft MIDCOM Protocol Semantics February 2003-] - outside port number: the external port number provided at the outside of the NAT (A2 in Fig. 3), see Section 2.3.5.. - policy rule lifetime: the policy rule lifetime [-granted by the middlebox. reply-parameters (failure): - an identifier matching the identifier of the request. - failure reason: the reason why the policy enable rule was rejected. The list of possible reasons includes but is not restricted to:-] {+granted by the middlebox. failure reason:+} - agent not authorized for this transaction - [-no such group --] agent not authorized for adding members to this group - no such policy reserve rule - agent not authorized for replacing this policy reserve rule - conflict with already existing policy rule (e.g. the same internal address-port is being mapped to different outside address-port pairs) - lack of IP addresses - lack of port numbers - lack of resources {+- no internal IP wildcarding allowed - no external IP wildcarding allowed+} semantics: This transactions can be used by an agent for enabling communication between an internal endpoint and an external endpoint [-independent-] {+independently+} of the type of middlebox (NAT, NAPT, firewall, NAT-PT, combined devices, ... [-)-] {+),+} for uni-directional or {+Stiemerling, Quittek, Taylor [Page 26] Internet-Draft MIDCOM Protocol Semantics May 2003+} bi-directional traffic. The agent sends an enable request specifying the endpoints (optionally including wildcards) and the direction of communication (inbound, outbound, bi-directional). The communication endpoints are displayed in Figure 3. The basic operation of the PER transaction can be described by 1. the agent sending A0 and A3 to the middlebox, 2. the middlebox reserving A1 and A2 or using A1 and A2 from a previous PRR transaction 3. the middlebox enabling packet transfer between A0 and A3 by binding A0-A2 and A1-A3 and/or by opening the corresponding pinholes, both according to the specified direction, 4. the middlebox returning A1 and A2 to the agent. [-Stiemerling, Quittek, Taylor [Page 25] Internet-Draft MIDCOM Protocol Semantics February 2003-] In case of a pure packet filtering firewall, the returned address tuples are the same as the ones in the request: A2=A0 and A1=A3. Each partner uses the other one's real address. In case of a traditional NAT the internal endpoint may use the real address of the external endpoint (A1=A3), but the external endpoint uses an address tuple provided by the NAT (A2!=A0). In case of a twice-NAT device, both endpoints [-uses-] {+use+} address tuples provided by the NAT for addressing their communication partner (A3!=A1 and A2!=A0). If a firewall is combined with a NAT or a twice-NAT, the replied address tuples will be the same as for pure traditional NAT or twice- NAT, respectively, but the middlebox will configure its packet filter in addition to the performed NAT bindings. In case of a firewall combined with a traditional NAT, {+the policy rule may imply+} more than one enable action [-might be required-] for the firewall configuration, because incoming and outgoing packets may use different source-destination pairs. {+Checking the policy reservation rule identifier+} If the {+parameter specifying the policy+} reservation {+rule+} identifier is not empty, then the middlebox checks whether or not the [-reference-] {+referenced+} policy rule [-exists and-] {+exists,+} whether or not the agent is authorized to replace this policy [-rule. If a non-existing policy rule group was specified,-] {+rule, and whether+} or [-if an existing policy rule group was specified that is-] not [-owned by the requesting agent, then no new-] {+this+} policy rule is [-established and an appropriate failure reply is generated.-] {+a policy reserve rule.+} In case of success, this transaction creates a new policy enable rule. If a policy reserve rule was referenced, then [-this-] {+the+} policy {+reserve+} rule is terminated without an explicit notification sent to the agent (besides the successful PER reply). [-If a policy rule group was specified, then the new policy rule becomes a member of it. If no policy group is specified a new group is created with the new policy rule as its only member.-] {+Stiemerling, Quittek, Taylor [Page 27] Internet-Draft MIDCOM Protocol Semantics May 2003+} The middlebox generates a middlebox unique identifier for the new policy rule. If a policy reserve rule was referenced, then the identifier of the policy reserve rule [-may be-] {+is+} re-used. The owner of the new policy rule [-is the authenticated agent that sent the request.-] {+is the authenticated agent that sent the request. Checking the policy rule group identifier If no policy reserve rule was specified, then the policy rule group parameter is checked. If a non-existing policy rule group is specified, or if an existing policy rule group is specified that is not owned by the requesting agent, then no new policy rule is established and an appropriate failure reply is generated. If an already exising policy rule group is specified, then the new policy rule becomes a member of it. If no policy group is specified, then a new group is created with the new policy rule as its only member.+} If the transport protocol parameter value is 'any', then the middlebox enables communication between the specified external IP address and the specified internal IP address. The addresses to be used by the communication partners in order to address each other are returned to the agent as inside IP address and outside IP address. If the reservation identifier is not empty and if the reservation used the same transport protocol type, then the reserved IP addresses are [-is-] used. [-Stiemerling, Quittek, Taylor [Page 26] Internet-Draft MIDCOM Protocol Semantics February 2003-] For the transport protocol parameter values 'UDP' and 'TCP' the middlebox acts analogously to [-'IP' with-] {+'ANY' but+} additionally [-mapping-] {+maps+} ranges of port [-numbers and-] {+numbers,+} keeping the port parity if requested. The configuration of the middlebox may fail because of lack of resources, such as available IP addresses, port numbers, or storage for further policy rules. Also it may fail because of a conflict with an already established policy rule. In case of a conflict, the first come first serve mechanism is applied. Already existing policy rules remain unchanged and arriving new ones are rejected. However, in case of a non-conflicting overlap of policy rules (including identical policy rules), all policy rules are accepted. {+The middlebox chooses a lifetime value that is greater than zero and less than or equal to the minimum of the requested value and the maximum lifetime specified by the middlebox at session startup, i.e.: 0 <= lt_granted <= MINIMUM(lt_requested, lt_maximum) Stiemerling, Quittek, Taylor [Page 28] Internet-Draft MIDCOM Protocol Semantics May 2003 whereas: - lt_granted is the actually granted lifetime by the middlebox - lt_requested is the requested lifetime of the agent - lt_maximum is the maximum liftime specified at session setup+} In each case of failure, an appropriate failure reply is generated. The policy reserve rule that is referenced in the PER transaction is not affected in case of a failure [-due to-] {+within+} the PER transaction, i.e. the policy reserve rule remains. 2.3.8. Policy Rule Lifetime Change (RLC) transaction-name: policy rule lifetime change transaction-type: configuration transaction-compliance: mandatory request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. - policy rule identifier: identifying the policy rule for which the lifetime is requested to be changed. This may identify either a policy reserve rule or a policy enable rule. - policy rule lifetime: the new lifetime proposal for the policy rule. reply-parameters (success): - request identifier: an identifier matching the identifier of the request. - policy rule lifetime: The remaining policy rule lifetime granted by the middlebox. [-reply-parameters (failure): Stiemerling, Quittek, Taylor [Page 27] Internet-Draft MIDCOM Protocol Semantics February 2003 - request identifier: an identifier matching the identifier of the request. --] failure reason: [-the reason why the lifetime change was rejected. The list of possible reasons includes but is not restricted to:-] - agent not authorized for this transaction - agent not authorized for changing lifetime of this policy rule - no such policy rule - lifetime cannot be extended semantics: The agent can use this transaction type to request an extension the lifetime of an already established policy rule, to request {+Stiemerling, Quittek, Taylor [Page 29] Internet-Draft MIDCOM Protocol Semantics May 2003+} shortening of the life time, or to request policy rule termination. Policy rule termination is requested by suggesting a new policy rule lifetime of zero. The middlebox first checks whether or not the specified policy rule exists and whether or not the agent is authorized to access this policy rule. If one of the checks fails, an appropriate failure reply is generated. If the requested lifetime is longer than the current one, the middlebox also checks, whether or not the lifetime of the policy rule may be extended and generates an appropriate failure message if not. A failure reply implies that the lifetime of the [-policy rule remains unchanged. A success reply-] {+policy rule remains unchanged. A success reply is generated by the middlebox, if the lifetime of the policy rule was changed in any way. The success reply contains the new lifetime of the policy rule. The middlebox chooses a lifetime value that is greater than zero and less than or equal to the minimum of the requested value and the maximum lifetime specified by the middlebox at session startup, i.e.: 0 <= lt_granted <= MINIMUM(lt_requested, lt_maximum) whereas: - lt_granted is the actually granted lifetime by the middlebox - lt_requested is the requested lifetime of the agent - lt_maximum+} is [-generated by-] the [-middlebox, if-] {+maximum liftime specified at session setup Editor's comment:+} the [-lifetime-] {+use+} of [-the-] {+group lifetimes as constraints on individual+} policy rule {+lifetimes+} was [-changed-] {+considered to be not necessary+} in [-any way. The-] {+IETF 54 discussion. After sending a+} success reply [-contains the new-] {+with a+} lifetime of {+zero,+} the [-policy rule. The-] middlebox [-chooses-] {+will consider+} the {+policy rule to be non-existent. It will not process any further transaction on this policy rule. Please note, that policy rule+} lifetime [-within the interval limited-] {+may also be changed+} by the [-lifetime-] {+Group Lifetime Change (GLC) transaction if applied to the group+} of {+which+} the policy rule {+is a member. 2.3.9. Policy Rule List (PRL) transaction-name: policy rule list transaction-type: monitoring transaction-compliance: optional Stiemerling, Quittek, Taylor [Page 30] Internet-Draft MIDCOM Protocol Semantics May 2003 request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply+} at [-arrival of-] the {+agent. reply-parameters (success): -+} request [-and by-] {+identifier: an identifier matching+} the [-suggested lifetime. The granted remaining lifetime must not exceed-] {+identifier of+} the [-maximum lifetime-] {+request. - policy list: list of policy rule identifiers of all policy rules+} that the [-middlebox specified at session setup together with its other capabilities. It also must-] {+agent can access. failure reason: - transaction not supported - agent not authorized for this transaction semantics: The agent can use this transaction type to list all policiess which it can access. Usually, the agent has this information already, but in special cases (for example after an agent failover) or for special agents (for example an administrating agent that can access all policies) this transaction can be helpful. The middlebox first checks whether or+} not [-exceed the lifetime of the group of which-] the [-policy rule-] {+agent+} is [-a member. Editor's comment: the use of group lifetimes as constraints on individual policy rule lifetimes was considered-] {+authorized+} to [-be not necessary in IETF 54 discussion. After sending a success-] {+request this transaction. If the check fails, an appropriate failure+} reply [-with-] {+is generated. Otherwise+} a [-lifetime-] {+list+} of [-zero,-] {+all policies+} the [-middlebox will consider-] {+agent can access is returned indicating+} the [-policy rule to be non-existent. It will-] {+identifier and the owner of each policy. This transaction does+} not [-process-] {+have+} any [-further transaction-] {+effect+} on [-this policy rule. Please note, that policy rule lifetime may also be changed by the Group Lifetime Change (GLC) transaction if applied to the group of Stiemerling, Quittek, Taylor [Page 28] Internet-Draft MIDCOM Protocol Semantics February 2003 which-] the policy rule [-is a member. 2.3.9.-] {+state. 2.3.10.+} Policy Rule Status (PRS) transaction-name: policy rule status transaction-type: monitoring transaction-compliance: optional request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. {+Stiemerling, Quittek, Taylor [Page 31] Internet-Draft MIDCOM Protocol Semantics May 2003+} - policy rule identifier: the middlebox unique policy rule identifier. reply-parameters (success): - request identifier: an identifier matching the identifier of the request. - policy rule owner: an identifier of the agent owning this policy rule. - group identifier: a reference to the group of which the policy rule is a member. - policy rule action: this parameter has either the value 'reserve' or the value 'enable'. - transport protocol: identifies the protocol for which a reservation is requested, see Section 2.3.5. - port range: the number of consecutive ports numbers, see Section 2.3.5. - direction: the direction of the communication enabled by the [-middlebox, see Section 2.3.5.-] {+middlebox. Applicable only to policy enable rules.+} - internal IP address version: the version of the internal IP address (IP version of A0 in Fig. 3) - external IP address version: the version of the external IP address (IP version of A3 in Fig. 3) - internal IP address: the IP address of the internal communication endpoint (A0 in Fig. 3), see Section 2.3.5. [-Stiemerling, Quittek, Taylor [Page 29] Internet-Draft MIDCOM Protocol Semantics February 2003-] - internal port number: the port number of the internal communication endpoint (A0 in Fig. 3), see Section 2.3.5. - external IP address: the IP address of the external communication endpoint (A3 in Fig. 3), see Section 2.3.5. - external port number: the port number of the external communication endpoint (A3 in Fig. 3), see Section 2.3.5. - inside IP address: the internal IP address provided at the inside of the NAT (A1 in Fig. 3), see Section 2.3.5. - inside port number: the internal port number provided at the inside of the NAT (A1 in Fig. 3), see Section 2.3.5. {+Stiemerling, Quittek, Taylor [Page 32] Internet-Draft MIDCOM Protocol Semantics May 2003+} - outside IP address: the external IP address provided at the outside of the NAT (A2 in Fig. 3), see Section 2.3.5. - outside port number: the external port number provided at the outside of the NAT (A2 in Fig. 3), see Section 2.3.5. - policy rule lifetime: the remaining lifetime of the policy rule. [-reply-parameters (failure): - request identifier: an identifier matching the identifier of the request. --] failure reason: [-the reason why the request for a status report was rejected. The list of possible reasons includes but is not restricted to:-] - transaction not supported - agent not authorized for this transaction - no such policy rule - agent not authorized for accessing this policy rule semantics: The agent can use this transaction type to list all properties of a policy rule. Usually, the agent has this information already, but in special cases (for example after an agent failover) or for special agents (for example an administrating agent that can access all policy rules) this optional transaction can be helpful. The middlebox first checks whether or not the specified policy rule exists and whether or not the agent is authorized to access this group. If one of the checks fails, an appropriate failure reply is generated. Otherwise all properties of the policy rule are returned to the agent. Some of the returned parameters may be irrelevant, depending on the policy rule action ('reserve' or [-Stiemerling, Quittek, Taylor [Page 30] Internet-Draft MIDCOM Protocol Semantics February 2003-] 'enable') and depending on other parameters, for example the protocol identifier. This transaction does not have any effect on the policy rule state. [-2.3.10.-] {+2.3.11.+} Asynchronous Policy Rule Deletion (ARD) transaction-name: asynchronous policy rule deletion transaction-type: notification transaction-compliance: mandatory notification-parameters: - policy rule identifier: the policy rule that will be deleted. - deletion reason: the reason why the middlebox will delete the policy rule. {+Stiemerling, Quittek, Taylor [Page 33] Internet-Draft MIDCOM Protocol Semantics May 2003+} semantics: The middlebox may decide at any point in time to delete a policy rule. Particularly, this transaction is triggered by lifetime expiration of the policy rule. Among other events that may cause this transaction are changes in the policy rule decision point. If this notification is generated, it is sent to all agents that are in an open session with the middlebox and that are authorized to access the policy rule. The notification is sent to the agents before the middlebox deletes the policy rule. After sending the notification, the middlebox will consider the policy rule to be non-existent. It will not process any further transaction on the policy rule. [-2.3.11.-] {+2.3.12.+} Policy Rule State Machine The state machine for the policy rule transactions is shown in Figure 4 with all possible state transitions. You'll find the used transaction abbreviations in the headings of [-the particular transaction section. Stiemerling, Quittek, Taylor [Page 31] Internet-Draft MIDCOM Protocol Semantics February 2003 PRR/failure PER/failure +-----------+ | v-] {+the particular transaction section.+} PRR/success [-+-+-------------+-] {++---------------++} +-----------------+ PRID UNUSED |<-+ +----+ | +---------------+ | | | | ^ | | | v v [-ARD-] | | | | +-------------+ [-PER/failure|-] {+ARD |+} | PER/ | ARD | | RESERVED +------------+ | success | RLC(lt=0)/ | +-+----+------+ RLC(lt=0)/ | | success | | | success | | +----+ | v | RLC(lt>0)/ | PER/success +---------------+ | success +---------------->| ENABLED +--+ [-RLC/failure-] +-+-------------+ | ^ [-+-----------+-] lt = lifetime {++-----------++} RLC(lt>0)/success [-RLC/failure-] Figure 4: Policy Rule State Machine This state machine exists per policy rule identifier (PRID). Initially, all policy rules are in state PRID UNUSED, which means that the policy rule does not exist or is not active. After returning to state [-RULE-] {+PRID+} UNUSED, the policy rule identifier is no longer bound to an existing policy rule and may be re-used by the middlebox. A successful PRR transaction causes a transition from the initial {+Stiemerling, Quittek, Taylor [Page 34] Internet-Draft MIDCOM Protocol Semantics May 2003+} state PRID UNSUSED to state RESERVED, where an address reservation is established. From there, state ENABLED can be entered by a PER transaction. This transaction can also be used for entering state ENABLED directly from state PRID UNUSED without a reservation. In state ENABLED the requested communication between the internal and the external endpoint is enabled. The states RESERVED and ENABLED can be maintained by a successful RLC transactions with a requested lifetime greater than 0. Transitions from both of these states back to state PRID UNUSED can be caused by an ARD transaction or by a successful RLC transaction with a lifetime parameter of 0. [-Additionally, a-] {+A+} failed [-PER transaction causes a transition from-] {+request transactions does not change+} state [-RESERVED to PRID UNUSED.-] {+at the middlebox.+} Please note, transitions initiated by RLC transactions may also be initiated by GLC transactions. [-Stiemerling, Quittek, Taylor [Page 32] Internet-Draft MIDCOM Protocol Semantics February 2003-] 2.4. Policy Rule Group Transactions This section describes the semantics for transactions on groups of policy rules. These transactions are specified: - Group Lifetime Change (GLC) - Group List (GL) - Group Status (GS) All are request transactions initiated by the agent. [-The status information transactions (GL-] {+GLC is a convenience transaction. GL+} and [-GS)-] {+GS are monitoring transactions that+} do not have any effect on the group state machine. 2.4.1. Overview A policy rule group has only one attribute: the list of its members. All member policies of a single group must be owned by the same authenticated agent. Therefore, an implicit property of a group is its owner, which is the owner of the member policy rules. A group is created implicitly, when its first member policy rule is established. A group us deleted implicitly, when the last remaining member policy rule is deleted. Consequently, the lifetime of a group is the maximum of the lifetimes of all member policy rules. A group has a middlebox unique identifier. Group transactions are [-redundant in the sense that they can be removed easily from the semantics specification without changing the set of possible middlebox configurations an agent can request. Therefore, all of them are-] declared as 'optional' by their respective compliance entry in Section 3. However, they provide some functionality, that is not available if only mandatory transactions {+Stiemerling, Quittek, Taylor [Page 35] Internet-Draft MIDCOM Protocol Semantics May 2003+} are available. The Group Lifetime Change (GLC) transaction is equivalent to [-simultaenously-] {+simultaneously+} performed Policy Rule Lifetime Change (RLC) transactions on all members of the group. The result of a successful GLC transaction is that all member policy rules have the same lifetime. Analogously to the RLC transaction, the GLC transaction can be use for deleting all member policy rules by requesting a lifetime of zero. The [-status information-] {+monitoring+} transactions Group List (GL) and Group Status (GS) can be used by the agent for exploring the state of the middlebox and for exploring its access rights. The GL transaction lists all groups that the agent may access, including groups owned by other agents. The GS transaction reports the status on an individual group and it lists all policy rules of this group by their policy [-Stiemerling, Quittek, Taylor [Page 33] Internet-Draft MIDCOM Protocol Semantics February 2003-] rule identifiers. The agent can explore the state of the individual policy rules by using the policy rule identifiers in a policy rule [-information-] {+status (PRS)+} transaction (see Section [-2.4.7).-] {+2.3.10). The GL and GS transactions are particularly helpful in case of an agent fail-over. The agent taking over the role of a failed one can use these transactions for retrieving which policies has been established by the failed agent.+} 2.4.2. Group Lifetime Change (GLC) transaction-name: group lifetime change transaction-type: [-configuration-] {+convenience+} transaction-compliance: optional request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. - group identifier: a reference to the group for which the lifetime is requested to be changed. - group lifetime: the new lifetime proposal for the group. reply-parameters (success): - request identifier: an identifier matching the identifier of the request. {+Stiemerling, Quittek, Taylor [Page 36] Internet-Draft MIDCOM Protocol Semantics May 2003+} - group lifetime: The group lifetime granted by the middlebox. [-reply-parameters (failure):-] {+failure reason:+} - request identifier: an identifier matching the identifier of the request. - failure reason: [-the reason why the lifetime change was rejected. The list of possible reasons includes but is not restricted to:-] - transaction not supported - agent not authorized for this transaction - agent not authorized for changing lifetime of this group - no such group - lifetime cannot be extended semantics: The agent can use this transaction type to request an extension of the lifetime of all members of a policy rule group, to request shortening the lifetime of all members, or to request deletion of all member policies (which implies deletion of the group). Deletion is requested by suggesting a new group lifetime of zero. [-Stiemerling, Quittek, Taylor [Page 34] Internet-Draft MIDCOM Protocol Semantics February 2003-] The middlebox first checks whether or not the specified group exists and whether or not the agent is authorized to access this group. If one of the checks fails, an appropriate failure reply is generated. If the requested lifetime is longer than the current one, the middlebox also checks whether or not the lifetime of the group may be extended and generates an appropriate failure message if not. A failure reply implies that the lifetime of the group remains unchanged. A success reply is generated by the middlebox if the lifetime of the group was changed in any way. The success reply contains the new common lifetime of all member policy rules of the group. The middlebox chooses the new lifetime less than or equal to the minimum of the requested lifetime and the maximum lifetime that the middlebox specified at session setup together with its other capabilities, i.e.: 0 <= lt_granted <= MINIMUM(lt_requested, lt_maximum) whereas: - lt_granted is the actually granted lifetime by the middlebox - lt_requested is the requested lifetime of the agent - lt_maximum is the maximum liftime specified at session setup After sending a success reply with a lifetime of zero, the member policy rules will be deleted without any further notification to the agent, and the middlebox will consider the group and all of its {+Stiemerling, Quittek, Taylor [Page 37] Internet-Draft MIDCOM Protocol Semantics May 2003+} members to be non-existent. It will not process any further transaction on this group or on any of its members. 2.4.3. Group List (GL) transaction-name: group list transaction-type: monitoring transaction-compliance: optional request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. reply-parameters (success): - request identifier: an identifier matching the identifier of the request. [-Stiemerling, Quittek, Taylor [Page 35] Internet-Draft MIDCOM Protocol Semantics February 2003-] - group list: list of all groups that the agent can access. For each listed [-group the identifier and the owner are indicated. reply-parameters (failure): - request identifier: an identifier matching the identifier of the request. - failure reason: the reason why the request for listing groups was rejected. The list of possible reasons includes but is not restricted to:-] {+group the identifier and the owner are indicated. failure reason:+} - transaction not supported - agent not authorized for this transaction semantics: The agent can use this transaction type to list all groups which it can access. Usually, the agent has this information already, but in special cases (for example after an agent failover) or for special agents (for example an administrating agent that can access all groups) this transaction can be helpful. The middlebox first checks whether or not the agent is authorized to request this transaction. If the check fails, an appropriate failure reply is generated. Otherwise a list of all groups the agent can access is returned indicating the identifier and the owner of each group. This transaction does not have any effect on the group state. 2.4.4. Group Status (GS) transaction-name: group status {+Stiemerling, Quittek, Taylor [Page 38] Internet-Draft MIDCOM Protocol Semantics May 2003+} transaction-type: monitoring transaction-compliance: optional request-parameters: - request identifier: an agent unique identifier for matching corresponding request and reply at the agent. - group identifier: a reference to the group for which status information is requested. reply-parameters (success): [-Stiemerling, Quittek, Taylor [Page 36] Internet-Draft MIDCOM Protocol Semantics February 2003-] - request identifier: an identifier matching the identifier of the request. - group owner: an identifier of the agent owning this policy rule group. - group lifetime: the remaining lifetime of the group. This is the maximum of the remaining lifetime of all members policy rules. - member list: list of all policy rules that are members of the group. The policy rules are specified by their middlebox unique policy rule identifier. [-reply-parameters (failure): - request identifier: an identifier matching the identifier of the request. --] failure reason: [-the reason why the request for a status report was rejected. The list of possible reasons includes but is not restricted to:-] - transaction not supported - agent not authorized for this transaction - no such group - agent not authorized for listing members of this group semantics: The agent can use this transaction type to list all member policy rules of a group. Usually, the agent has this information already, but in special cases (for example after an agent failover) or for special agents (for example an administrating agent that can access all groups) this transaction can be helpful. The middlebox first checks whether or not the specified group exists and whether or not the agent is authorized to access this group. If one of the checks fails, an appropriate failure reply is generated. Otherwise a list of all group members is returned indicating the identifier of each group. This transaction does not have any effect on the group state. {+Stiemerling, Quittek, Taylor [Page 39] Internet-Draft MIDCOM Protocol Semantics May 2003+} 3. Conformance Statements A protocol definition complies with the semantics defined in Section 2 if the protocol specification includes all specified transactions with all their parameters. However, concrete implementations of the protocol may not support some of the optional transactions. Which transactions are required for compliancy is different for agent and [-Stiemerling, Quittek, Taylor [Page 37] Internet-Draft MIDCOM Protocol Semantics February 2003-] middlebox. This section contains conformance statements for MIDCOM protocol implementations related to the semantics. Conformance is specified differently for agents and middleboxes. Most probably these conformance statements will be extended by a concrete protocol specification. However, such an extension is expected to extend the statements below in a way that all of them still hold. The following list shows the transaction-compliance property of all transactions as specified in the previous section: - Session Control Transactions - Session Establishment (SE) mandatory - Session Termination (ST) mandatory - Asynchronous Session Termination (AST) mandatory - Policy Rule Group Transactions - Group Lifetime Change (GLC) optional - Group List (GL) optional - Group Status (GS) optional - Policy Rule Transactions - Policy Reserve Rule (PRR) mandatory - Policy Enable Rule (PER) mandatory - Policy Rule Lifetime Change (RLC) mandatory - Policy Rule {+List (PRL) optional - Policy Rule+} Status (PRS) optional - Asynchronous Policy Rule Deletion (ARD) mandatory 3.1. General Implementation Conformance A compliant implementation of a MIDCOM protocol must support all mandatory transactions. A compliant implementation of a MIDCOM protocol may support none, one, or more of the following transactions: GLC, GL, GS, {+PRL,+} PRS. {+A compliant implementation may extend the protocol semantics by further transactions. A compliant implementation of a MIDCOM protocol must support all Stiemerling, Quittek, Taylor [Page 40] Internet-Draft MIDCOM Protocol Semantics May 2003 parameters of each transaction concerning the information contained. The set of parameters can be redefined per transaction as long as the contained information is maintained. A compliant implementation may extend the list of parameters of transactions. A compliant implementation may replace a single transaction by a set of more fine-grained transactions. In such a case, it must be ensured, that requirement 2.1.4 (deterministic behavior) and requirement 2.1.5 (known and stable state) of [MDC-REQ] are still met. Also there still must exist a composed transaction consisting of a sequence of transactions fine-grained transactions, which is equivalent to a single transaction defined in this document, and for which the atomicity requirement stated in Section 2.1.3 is met. A compliant implementation+} 3.2. Middlebox Conformance A middlebox implementation of a MIDCOM protocol supports a request transaction if it is able to receive and process all possible correct message instances of the particular request transaction and if it generates a correct reply for any correct request it receives. A middlebox implementation of a MIDCOM protocol supports a notification transaction if it is able to to generate the corresponding notification message properly. A compliant middlebox implementation of a MIDCOM protocol must inform [-Stiemerling, Quittek, Taylor [Page 38] Internet-Draft MIDCOM Protocol Semantics February 2003-] the agent about the list of supported transactions within the SE transaction. 3.3. Agent Conformance An agent implementation of a MIDCOM protocol supports a request transaction if it is able to generate the corresponding request message properly and if it is able to receive and process all possible correct replies to the particular request. An agent implementation of a MIDCOM protocol supports a notification transaction if it is able to receive and process all possible correct message instances of the particular transaction. A compliant agent implementation of a MIDCOM protocol must not use any optional transaction that is not supported by the middlebox. The middlebox informs the agent about the list of supported transactions within the SE transaction. {+Stiemerling, Quittek, Taylor [Page 41] Internet-Draft MIDCOM Protocol Semantics May 2003+} 4. Transaction Usage Examples This section gives two usage examples of the transactions specified in Section 2. First it is shown, how an agent can explore all policy rules and policy rule groups, which it may access at a middlebox. Then the middlebox configuration for enabling a SIP-signaled call is demonstrated. 4.1. Exploring Policy Rules and Policy Rule Groups This example precludes an already established session. It shows how an agent can find out - which groups it may access and who owns these groups - the status and member list of all accessible groups - the status and properties of all accessible policy rules If there is just a single session, there is no need for any of these actions, because the middlebox informs the agent about each state transition of any policy rule or policy rule group. However, after the disruption of a session or after an intentional session termination, the agent might want to re-establish the session and explore, which of the groups and policy rules it established are still in place. Also an agent system may fail and another one takes over. Then the other one need to find out what has already been configured by the failing system and what still needs to be done. [-Stiemerling, Quittek, Taylor [Page 39] Internet-Draft MIDCOM Protocol Semantics February 2003-] A third situation where exploring policy rules and groups is useful is the case of an agent with 'administrator' authorization. This agent may access any policy rule or group created by any other agent and modify them. All of them probably will start their exploration with the Group List (GL) transaction, as shown in Figure 5. On this request, the middlebox returns a list of pairs each containing an agent identifier and a group identifier (GID). The agent gets informed which own group and which of other agents' groups it may access. {+Stiemerling, Quittek, Taylor [Page 42] Internet-Draft MIDCOM Protocol Semantics May 2003+} agent middlebox | GL | |**********************************************>| |<**********************************************| | (agent1,GID1) (agent1,GID2) (agent2,GID3) | | | | GS GID2 | |**********************************************>| |<**********************************************| | agent1 lifetime PID1 PID2 PID3 PID4 | | | Figure 5: Using the GL and the GS transaction In Figure 5 three groups are accessible to the agent, and the agent retrieves information about the second group by using the Group Status (GS) transaction. It receives the owner of the group, the remaining lifetime, and the list of member policy rules, in this case containing four policy rule identifiers (PIDs). In the following, the agent explores these four policy rules. The example assumes the middlebox to be a traditional NAPT. Figure 6 shows the exploration of the first policy rule. As reply to a Policy Rule Status (PRS) transaction, the middlebox always returns the following list of parameters: - policy rule owner - group identifier - policy rule action (reserve or enable) - protocol type - port range - direction - internal IP address - internal port number - external address - external port number - [-NAT-] {+middlebox+} inside IP address - [-NAT-] {+middlebox+} inside port number [-Stiemerling, Quittek, Taylor [Page 40] Internet-Draft MIDCOM Protocol Semantics February 2003-] - [-NAT-] {+middlebox+} outside IP address - [-NAT-] {+middlebox+} outside port number - IP address versions (not printed) {+Stiemerling, Quittek, Taylor [Page 43] Internet-Draft MIDCOM Protocol Semantics May 2003+} agent middlebox | PRS PID1 | |**********************************************>| |<**********************************************| | agent1 GID2 RESERVE UDP 1 | | ANY ANY ANY ANY | | ANY ANY IPADR_OUT PORT_OUT1 | | | Figure 6: Status report for an outside reservation The `ANY' parameter printed in Figure 6 is [-equal to the `zero' IP addresses define-] {+used as a placeholder+} in [-section 2.3.5.-] {+policy rules status replies for policy reserve rules.+} The policy rule with PID1 is a policy reserve rule for UDP traffic at the outside of the middlebox. Since there is no internal or external address involved yet, these four fields are wildcarded in the reply. The same holds for the inside [-NAT-] {+middlebox+} address and port number. The only address information given by the reply is the reserved outside IP address of the [-NAT-] {+middlebox+} (IPADDR_OUT) and the corresponding port number (PORT_OUT1). Note, that IPADR_OUT and PORT_OUT1 may not be wildcarded, because the reserve action does not support this. Applying PRS to PID2 (Figure 7) shows that the second policy rule is an policy enable rule for inbound UDP packets. The internal destination is fixed concerning IP address, protocol and port number, but for the external source, the port number is wildcarded. The outside IP address and port number of the middlebox are the ones the external sender needs to use as destination in the original packet it sends. At the middlebox, the destination address is replaced with the internal address of the final receiver. During address translation, the source IP address and the source port numbers of the packets remain unchanged. This is indicated by the inside address which is identical to the external address. agent middlebox | PRS PID2 | |**********************************************>| |<**********************************************| | agent1 GID2 ENABLE UDP 1 IN | | IPADR_INT PORT_INT1 IPADR_EXT ANY | | IPADR_EXT ANY IPADR_OUT PORT_OUT2 | | | Figure 7: Status report for enabled inbound packets [-Stiemerling, Quittek, Taylor [Page 41] Internet-Draft MIDCOM Protocol Semantics February 2003-] For traditional NATs the identity of the inside IP address and port number with the external IP address and port number always holds (A1=A3 in Figure 3). For a pure firewall, also the outside IP address and port number are always identical with the internal IP address and port number (A0=A2 in Figure 3). {+Stiemerling, Quittek, Taylor [Page 44] Internet-Draft MIDCOM Protocol Semantics May 2003+} agent middlebox | PRS PID3 | |**********************************************>| |<**********************************************| | agent1 GID2 ENABLE UDP 1 OUT | | IPADR_INT PORT_INT2 IPADR_EXT PORT_EXT1 | | IPADR_EXT PORT_EXT1 IPADR_OUT PORT_OUT3 | | | Figure 8: Status report for enabled outbound packets Figure 8 shows enabled outbound UDP communication between the same host. Here all port numbers are known. Since again A1=A3, the internal sender uses the external IP address and port number as destination in the original packets. At the firewall, the internal source IP address and port number are replaced by the shown outside IP address and port number of the middlebox. agent middlebox | PRS PID4 | |**********************************************>| |<**********************************************| | agent1 GID2 ENABLE TCP 1 BI | | IPADR_INT PORT_INT3 IPADR_EXT PORT_EXT2 | | IPADR_EXT PORT_EXT2 IPADR_OUT PORT_OUT4 | | | Figure 9: Status report for bi-directional TCP traffic Finally, Figure 9 shows the status report for enabled bi-directional TCP traffic. Please note that still A1=A3: For outbound packets, only the source IP address and port number are replaced at the middlebox, and for inbound packets, only the destination IP address and port number are replaced. 4.2. Enabling a SIP-Signaled Call This elaborated transaction usage example shows the interaction between a SIP proxy and a middlebox. The middlebox itself is a traditional [-NAPT-] {+Network Address and Port Translation (NAPT)+} and two user agents communicate with each other via the SIP proxy and NAPT as shown in figure 10. Stiemerling, Quittek, Taylor [Page [-42]-] {+45]+} Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 +----------+ |SIP Proxy | |for domain| | mb.com | +----------+ Private ^ ^ Public Network Network | | +----------+ | | +---------+ +----------+ |User Agent|<-+ +->|Middlebox|<------->|User Agent| | A |<#######>| NAPT |<#######>| B | +----------+ +---------+ +----------+ <--> SIP Signalling <##> RTP Traffic Figure 10: Example SIP Scenario For the below sequence charts we make these assumptions: - The NAPT is statically configured to forward SIP signalling from the outside to the SIP proxy server, i.e. traffic to the NAPT's external IP address and port 5060 is forwarded to the internal SIP proxy. - The user agent A, located inside the private network, is registered at the SIP proxy with its private IP address. - User A knows the general SIP URL of user B. The URL is B@b.de. However, the concrete URL of the SIP User Agent B, which user B currently uses, is not known. - Only the RTP paths are configured, but not the RTCP paths. - The middlebox and the SIP server share an already established MIDCOM session. - Some parameters are omitted, like the request identifier (RID) Furthermore these abbreviations are used: - IP_AI: Internal IP address of user agent A - P_AI: Internal port number of user agent A to receive RTP data - P_AE: External mapped port number of user agent A - IP_AE: External IP address of the middlebox - IP_B: IP address of user agent B - P_B: Port number of user agent B to receive RTP data - GID: Group identifier Stiemerling, Quittek, Taylor [Page [-43]-] {+46]+} Internet-Draft MIDCOM Protocol Semantics [-February-] {+May+} 2003 - PID: Policy rule identifier The abbreviations of the MIDCOM transactions can be found in the particular section headings. In our example, user A tries to call user B. Therefore, the user agent A sends an INVITE SIP message to the SIP proxy server (see Figure 10). The SDP part of the particular SIP message that is relevant for the middlebox configuration is shown in the sequence chart as: SDP: m=..P_AI.. c=IP_AI where the m tag is the media tag which contains the receiving UDP port number and the c tag contains the IP address of the terminal receiving the media stream. The INVITE message forwarded to user agent B must contain a public IP address and [-a-] {+a port number to which user agent B can send its RTP media stream. The SIP proxy requests a policy enable rule at the middlebox with a PER request with wildcarded IP address and port number of user agent B. Since neither IP address nor port numbers of user agent B are known at this point of time, the address of user agent B must be wildcarded. The wildcarded IP address and port number enables the 'early media' capability, but results as well in some insecurity, since any host can on the enabled port number through the middlebox to user agent A. User Agent SIP Middlebox User Agent A Proxy NAPT B | | | | | INIVTE B@B.DE | | | | SDP:m=..P_AI.. | | | | c=IP_AI | | | |--------------->| | | | | | | | | PER PID1 UDP 1 EVEN IN | | | | IP_AI P_AI ANY ANY 300s | | | |*****************************>| | | |<*****************************| | | | PER OK GID1 PID1 ANY ANY | | | | IP_AE P_AE1 300s | | Figure 11: PER with wildcard address and+} port number {+A successfully PER reply, as shown in Figure 11, results in a NAT binding at the middlebox. This binding enables UDP traffic from any host outside of user agent A's private network+} to [-which-] {+reach user agent A. So+} user agent B {+could start sending traffic immediately after Stiemerling, Quittek, Taylor [Page 47] Internet-Draft MIDCOM Protocol Semantics May 2003 receiving the INVITE message, and so+} can [-send its RTP media stream. Therefore,-] {+do any other host. Even hosts that are not intended to be a particpant, like any malicious host. In the case the middlebox does not support or does not permit IP address wildcarding for security reasons, the PER request will be rejected with an appropriate failure reason, like 'IP wildcarding not supported'. Nevertheless,+} the SIP proxy server needs an outside IP address and port number at the middlebox (the NAPT) {+in order+} to [-be available for this purpose. However, since-] {+forward+} the {+SIP INVITE message. T