summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc6970.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc6970.txt')
-rw-r--r--doc/rfc/rfc6970.txt1291
1 files changed, 1291 insertions, 0 deletions
diff --git a/doc/rfc/rfc6970.txt b/doc/rfc/rfc6970.txt
new file mode 100644
index 0000000..071cbda
--- /dev/null
+++ b/doc/rfc/rfc6970.txt
@@ -0,0 +1,1291 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) M. Boucadair
+Request for Comments: 6970 France Telecom
+Category: Standards Track R. Penno
+ISSN: 2070-1721 D. Wing
+ Cisco
+ July 2013
+
+
+ Universal Plug and Play (UPnP)
+ Internet Gateway Device - Port Control Protocol Interworking Function
+ (IGD-PCP IWF)
+
+Abstract
+
+ This document specifies the behavior of the Universal Plug and Play
+ (UPnP) Internet Gateway Device - Port Control Protocol Interworking
+ Function (IGD-PCP IWF). A UPnP IGD-PCP IWF is required to be
+ embedded in Customer Premises (CP) routers to allow for transparent
+ NAT control in environments where a UPnP IGD is used on the LAN side
+ and PCP is used on the external side of the CP router.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6970.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 1]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+Copyright Notice
+
+ Copyright (c) 2013 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+Table of Contents
+
+ 1. Introduction ....................................................3
+ 1.1. Requirements Language ......................................3
+ 2. Acronyms ........................................................4
+ 3. Architecture Model ..............................................4
+ 4. UPnP IGD-PCP IWF: Overview ......................................6
+ 4.1. UPnP IGD-PCP: State Variables ..............................6
+ 4.2. IGD-PCP: Methods ...........................................7
+ 4.3. UPnP IGD-PCP: Errors .......................................8
+ 5. Specification of the IGD-PCP IWF ................................9
+ 5.1. PCP Server Discovery .......................................9
+ 5.2. Control of the Firewall ...................................10
+ 5.3. Port Mapping Table ........................................10
+ 5.4. Interworking Function without NAT in the IGD ..............10
+ 5.5. NAT Embedded in the IGD ...................................11
+ 5.6. Creating a Mapping ........................................12
+ 5.6.1. AddAnyPortMapping() ................................12
+ 5.6.2. AddPortMapping() ...................................13
+ 5.7. Listing One or a Set of Mappings ..........................16
+ 5.8. Delete One or a Set of Mappings: DeletePortMapping() or
+ DeletePortMappingRange() ..................................16
+ 5.9. Renewing a Mapping ........................................19
+ 5.10. Rapid Recovery ...........................................20
+ 6. Security Considerations ........................................21
+ 7. Acknowledgments ................................................21
+ 8. References .....................................................22
+ 8.1. Normative References ......................................22
+ 8.2. Informative References ....................................22
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 2]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+1. Introduction
+
+ The Port Control Protocol (PCP) specification [RFC6887] discusses the
+ implementation of NAT control features that rely upon Carrier Grade
+ NAT devices such as a Dual-Stack Lite (DS-Lite) Address Family
+ Transition Router (AFTR) [RFC6333] or NAT64 [RFC6146]. In
+ environments where a Universal Plug and Play Internet Gateway Device
+ (UPnP IGD) is used in the local network, an interworking function
+ between the UPnP IGD and PCP is required to be embedded in the IGD
+ (see the example illustrated in Figure 1).
+
+ UPnP IGD-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | IGD |
+ | | |
+ | (1) AddPortMapping() | |
+ |----------------------->| |
+ | | (2) PCP MAP Request |
+ | |-------------------------->|
+ | | |
+
+ Figure 1: Flow Example
+
+ Two configurations are considered within this document:
+
+ o No NAT function is embedded in the IGD (Section 5.4). This is
+ required, for instance, in DS-Lite or NAT64 deployments.
+
+ o The IGD embeds a NAT function (Section 5.5).
+
+ The UPnP IGD-PCP Interworking Function (UPnP IGD-PCP IWF) maintains a
+ local mapping table that stores all active mappings constructed by
+ internal IGD Control Points. This design choice restricts the amount
+ of PCP messages to be exchanged with the PCP server.
+
+ Triggers for deactivating the UPnP IGD-PCP IWF from the IGD and
+ relying on a PCP-only mode are out of scope for this document.
+
+ Considerations related to co-existence of the UPnP IGD-PCP
+ Interworking Function and a PCP Proxy [PCP-PROXY] are out of scope.
+
+1.1. Requirements Language
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [RFC2119].
+
+
+
+
+Boucadair, et al. Standards Track [Page 3]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+2. Acronyms
+
+ This document makes use of the following abbreviations:
+
+ DS-Lite - Dual-Stack Lite
+ IGD - Internet Gateway Device
+ IGD:1 - UPnP Forum's nomenclature for version 1 of IGD [IGD1]
+ IGD:2 - UPnP Forum's nomenclature for version 2 of IGD [IGD2]
+ IWF - Interworking Function
+ NAT - Network Address Translation
+ PCP - Port Control Protocol
+ UPnP - Universal Plug and Play
+
+3. Architecture Model
+
+ As a reminder, Figure 2 illustrates the architecture model as adopted
+ by the UPnP Forum [IGD2]. In Figure 2, the following UPnP
+ terminology is used:
+
+ o 'Client' refers to a host located in the local network.
+
+ o 'IGD Control Point' is a device using UPnP to control an IGD
+ (Internet Gateway Device).
+
+ o 'IGD' is a router supporting a UPnP IGD. It is typically a NAT or
+ a firewall.
+
+ o 'Host' is a remote peer reachable in the Internet.
+
+ +-------------+
+ | IGD Control |
+ | Point |-----+
+ +-------------+ | +-----+ +------+
+ +---| | | |
+ | IGD |-------| Host |
+ +---| | | |
+ +-------------+ | +-----+ +------+
+ | Client |-----+
+ +-------------+
+
+ Figure 2: UPnP IGD Model
+
+ This model is not valid when PCP is used to control, for instance, a
+ Carrier Grade NAT (aka Provider NAT) while internal hosts continue to
+ use a UPnP IGD. In such scenarios, Figure 3 shows the updated model.
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 4]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ +-------------+
+ | IGD Control |
+ | Point |----+
+ +-------------+ | +-----+ +--------+ +------+
+ +---| IGD-| |Provider| |Remote|
+ | PCP |------| NAT |--<Internet>---| Host |
+ +---| IWF | | | | |
+ +-------------+ | +-----+ +--------+ +------+
+ | Local Host |----+
+ +-------------+
+ LAN Side External Side
+ <======UPnP IGD==============><=====PCP=====>
+
+ Figure 3: UPnP IGD-PCP Interworking Model
+
+ In the updated model depicted in Figure 3, one or two levels of NAT
+ can be encountered in the data path. Indeed, in addition to the
+ Carrier Grade NAT, the IGD may embed a NAT function (Figure 4).
+
+ +-------------+
+ | IGD Control |
+ | Point |----+
+ +-------------+ | +-----+ +--------+ +------+
+ +---| IGD-| |Provider| |Remote|
+ | PCP |------| NAT |--<Internet>---| Host |
+ +---| IWF | | | | |
+ +-------------+ | +-----+ +--------+ +------+
+ | Local Host |----+ NAT1 NAT2
+ +-------------+
+
+ Figure 4: Cascaded NAT Scenario
+
+ To ensure successful interworking between a UPnP IGD and PCP, an
+ interworking function is embedded in the IGD. In the model defined
+ in Figure 3, all UPnP IGD server-oriented functions, a PCP client
+ [RFC6887], and a UPnP IGD-PCP Interworking Function are embedded in
+ the IGD. In the rest of the document, "IGD-PCP IWF" refers to the
+ UPnP IGD-PCP Interworking Function, which includes PCP client
+ functionality.
+
+ Without the involvement of the IGD-PCP IWF, the IGD Control Point
+ would retrieve an external IP address and port number that have
+ limited scope and that cannot be used to communicate with hosts
+ located beyond NAT2 (i.e., assigned by the IGD, and not those
+ assigned by NAT2 as depicted in Figure 4).
+
+ The UPnP IGD-PCP IWF is responsible for generating a well-formed PCP
+ message from a received UPnP IGD message, and vice versa.
+
+
+
+Boucadair, et al. Standards Track [Page 5]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+4. UPnP IGD-PCP IWF: Overview
+
+ Three tables are provided to specify the correspondence between a
+ UPnP IGD and PCP:
+
+ (1) Section 4.1 provides the mapping between WANIPConnection state
+ variables and PCP parameters;
+
+ (2) Section 4.2 focuses on the correspondence between supported
+ methods;
+
+ (3) Section 4.3 lists the PCP error messages and their corresponding
+ IGD error messages.
+
+ Note that some enhancements have been integrated in WANIPConnection,
+ as documented in [IGD2].
+
+4.1. UPnP IGD-PCP: State Variables
+
+ Below are listed only the UPnP IGD state variables applicable to the
+ IGD-PCP IWF:
+
+ ExternalIPAddress: External IP Address
+ Read-only variable with the value from the last PCP response, or
+ the empty string if none was received yet. This state is stored
+ on a per-IGD-Control-Point basis.
+
+ PortMappingNumberOfEntries: Managed locally by the UPnP IGD-PCP IWF.
+
+ PortMappingEnabled:
+ PCP does not support deactivating the dynamic NAT mapping, since
+ the initial goal of PCP is to ease the traversal of Carrier Grade
+ NAT. Supporting such per-subscriber function may overload the
+ Carrier Grade NAT.
+ Only "1" is allowed: i.e., the UPnP IGD-PCP Interworking Function
+ MUST send back an error if a value different from 1 is signaled.
+
+ PortMappingLeaseDuration: Requested Mapping Lifetime
+ In IGD:1 [IGD1], the value 0 means infinite; in IGD:2, it is
+ remapped to the IGD maximum of 604800 seconds [IGD2]. PCP allows
+ for a maximum value of 4294967296 seconds.
+ The UPnP IGD-PCP Interworking Function simulates long and even
+ infinite lifetimes using renewals (see Section 5.9). The behavior
+ of the UPnP IGD-PCP IWF in the case of a failing renewal is
+ currently undefined (see Section 5.9).
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 6]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ IGD:1 doesn't define the behavior in the case of state loss; IGD:2
+ doesn't require that state be kept in stable storage, i.e., to
+ allow the state to survive resets/reboots. The UPnP IGD-PCP
+ Interworking Function MUST support IGD:2 behavior.
+
+ RemoteHost: Remote Peer IP Address
+ Note that IGD:2 allows a domain name, which has to be resolved to
+ an IP address. Mapped to the Remote Peer IP Address field of the
+ FILTER option.
+
+ ExternalPort: External Port Number
+ Mapped to the Suggested External Port field in MAP messages.
+
+ InternalPort: Internal Port Number
+ Mapped to the Internal Port field in MAP messages.
+
+ PortMappingProtocol: Protocol
+ Mapped to the Protocol field in MAP messages. Note that a UPnP
+ IGD only supports TCP and UDP.
+
+ InternalClient: Internal IP Address
+ Note that IGD:2 allows a domain name, which has to be resolved to
+ an IP address. Mapped to the Internal IP Address field of the
+ THIRD_PARTY option.
+
+ PortMappingDescription: Not supported in base PCP.
+ If the local PCP client supports a PCP option to convey the
+ description (e.g., [PCP-DESCR-OPT]), this option SHOULD be used to
+ relay the mapping description.
+
+ SystemUpdateID (IGD:2 only): Managed locally by the UPnP IGD-PCP
+ IWF.
+
+ A_ARG_TYPE_PortListing (IGD:2 only): Managed locally by the UPnP
+ IGD-PCP IWF.
+
+4.2. IGD-PCP: Methods
+
+ IGD:1 and IGD:2 methods applicable to the UPnP IGD-PCP Interworking
+ Function are both listed here.
+
+ GetGenericPortMappingEntry(): This request is not relayed to the PCP
+ server.
+
+ The IGD-PCP Interworking Function maintains a list of active
+ mappings instantiated in the PCP server by internal hosts. See
+ Section 5.7 for more information.
+
+
+
+
+Boucadair, et al. Standards Track [Page 7]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ GetSpecificPortMappingEntry(): MAP with PREFER_FAILURE option.
+
+ This request is relayed to the PCP server by issuing a MAP request
+ with the PREFER_FAILURE option. It is RECOMMENDED to use a short
+ lifetime (e.g., 60 seconds).
+
+ AddPortMapping(): MAP
+ See Section 5.6.2.
+
+ AddAnyPortMapping() (IGD:2 only): MAP
+ See Section 5.6.1.
+
+ DeletePortMapping(): MAP with Requested Lifetime set to 0.
+ See Section 5.8.
+
+ DeletePortMappingRange() (IGD:2 only): MAP with Requested Lifetime
+ set to 0.
+ Individual requests are issued by the IGD-PCP IWF. See
+ Section 5.8 for more details.
+
+ GetExternalIPAddress(): MAP
+ This can be learned from any active mapping. If there are no
+ active mappings, the IGD-PCP IWF MAY request a short-lived mapping
+ (e.g., to the Discard service (TCP/9 or UDP/9) or some other
+ port). However, once that mapping expires, a subsequent implicit
+ or explicit dynamic mapping might be mapped to a different
+ external IP address. See Section 11.6 of [RFC6887] for more
+ discussion.
+
+ GetListOfPortMappings(): See Section 5.7 for more information.
+ The IGD-PCP Interworking Function maintains a list of active
+ mappings instantiated in the PCP server. The IGD-PCP Interworking
+ Function handles this request locally.
+
+4.3. UPnP IGD-PCP: Errors
+
+ This section lists PCP error codes and the corresponding UPnP IGD
+ codes. Error codes specific to IGD:2 are tagged accordingly.
+
+ 1 UNSUPP_VERSION: 501 "ActionFailed"
+
+ 2 NOT_AUTHORIZED: IGD:1 718 "ConflictInMappingEntry" / IGD:2 606
+ "Action not authorized"
+
+ 3 MALFORMED_REQUEST: 501 "ActionFailed"
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 8]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ 4 UNSUPP_OPCODE: 501 "ActionFailed"
+ [RFC6887] allows the PCP server to be configured to disable
+ support for the MAP Opcode, but the IGD-PCP IWF cannot work in
+ this situation.
+
+ 5 UNSUPP_OPTION: 501 "ActionFailed"
+ This error code can be received if PREFER_FAILURE is not supported
+ on the PCP server. Note that PREFER_FAILURE is not mandatory to
+ support, but AddPortMapping() cannot be implemented without it.
+
+ 6 MALFORMED_OPTION: 501 "ActionFailed"
+
+ 7 NETWORK_FAILURE: 501 "ActionFailed"
+
+ 8 NO_RESOURCES: IGD:1 501 "ActionFailed" / IGD:2 728
+ "NoPortMapsAvailable"
+ Cannot be distinguished from USER_EX_QUOTA.
+
+ 9 UNSUPP_PROTOCOL: 501 "ActionFailed"
+
+ 10 USER_EX_QUOTA: IGD:1 501 "ActionFailed" / IGD:2 728
+ "NoPortMapsAvailable"
+ Cannot be distinguished from NO_RESOURCES.
+
+ 11 CANNOT_PROVIDE_EXTERNAL: 718 "ConflictInMappingEntry" (see
+ Section 5.6.2) or 714 "NoSuchEntryInArray" (see Section 5.8).
+
+ 12 ADDRESS_MISMATCH: 501 "ActionFailed"
+
+ 13 EXCESSIVE_REMOTE_PEERS: 501 "ActionFailed"
+
+5. Specification of the IGD-PCP IWF
+
+ This section covers scenarios with or without NAT in the IGD.
+
+ This specification assumes that the PCP server is configured to
+ accept the MAP Opcode.
+
+ The IGD-PCP IWF handles the "Mapping Nonce" the same way as any PCP
+ client [RFC6887].
+
+5.1. PCP Server Discovery
+
+ The IGD-PCP IWF implements one of the discovery methods identified in
+ [RFC6887] (e.g., DHCP [PCP-DHCP-OPT]). The IGD-PCP Interworking
+ Function behaves as a PCP client when communicating with provisioned
+ PCP server(s).
+
+
+
+
+Boucadair, et al. Standards Track [Page 9]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ If no IPv4 address/IPv6 prefix is assigned to the IGD or the IGD is
+ unable to determine whether it should contact an upstream PCP server,
+ the IGD-PCP Interworking Function MUST NOT be invoked.
+
+ If the IGD determines that it should establish communication with an
+ upstream PCP server (e.g., because of DHCP configuration or having
+ previously communicated with a PCP server), a "501 ActionFailed"
+ error message is returned to the requesting IGD Control Point if the
+ IGD-PCP IWF fails to establish communication with that PCP server.
+ Note that the IGD-PCP IWF proceeds to PCP message validation and
+ retransmission the same way as any PCP client [RFC6887].
+
+5.2. Control of the Firewall
+
+ In order to configure security policies to be applied to inbound and
+ outbound traffic, a UPnP IGD can be used to control a local firewall
+ engine. No IGD-PCP IWF is therefore required for that purpose.
+
+ The use of the IGD-PCP IWF to control an upstream PCP-controlled
+ firewall is out of scope for this document.
+
+5.3. Port Mapping Table
+
+ The IGD-PCP IWF MUST store locally all the mappings instantiated by
+ internal IGD Control Points in the PCP server. All mappings SHOULD
+ be stored in permanent storage.
+
+ Upon receipt of a PCP MAP response from the PCP server, the IGD-PCP
+ Interworking Function MUST extract the enclosed mapping and MUST
+ store it in the local mapping table. The local mapping table is an
+ image of the mapping table as maintained by the PCP server for a
+ given subscriber.
+
+ Each mapping entry stored in the local mapping table is associated
+ with a lifetime as discussed in [RFC6887]. Additional considerations
+ specific to the IGD-PCP Interworking Function are discussed in
+ Section 5.9.
+
+5.4. Interworking Function without NAT in the IGD
+
+ When no NAT is embedded in the IGD, the contents of received
+ WANIPConnection and PCP messages are not altered by the IGD-PCP
+ Interworking Function (i.e., the contents of WANIPConnection messages
+ are mapped to PCP messages (and mapped back), according to
+ Section 4.1).
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 10]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+5.5. NAT Embedded in the IGD
+
+ When NAT is embedded in the IGD, the IGD-PCP IWF updates the contents
+ of mapping messages received from the IGD Control Point. These
+ messages will contain an IP address and/or port number that belong to
+ an internal host. The IGD-PCP IWF MUST update such messages with the
+ IP address and/or port number belonging to the external interface of
+ the IGD (i.e., after the NAT1 operation as depicted in Figure 4).
+
+ The IGD-PCP IWF intercepts all WANIPConnection messages issued by the
+ IGD Control Point. For each such message, the IGD-PCP IWF then
+ generates one or more corresponding requests (see Sections 4.1, 4.2,
+ and 4.3) and sends them to the provisioned PCP server.
+
+ Each request sent by the IGD-PCP IWF to the PCP server MUST reflect
+ the mapping information as enforced in the first NAT. Particularly,
+ the internal IP address and/or port number of the requests are
+ replaced with the IP address and/or port number as assigned by the
+ NAT of the IGD. For the reverse path, the IGD-PCP IWF intercepts PCP
+ response messages and generates WANIPConnection response messages.
+ The contents of the generated WANIPConnection response messages are
+ set as follows:
+
+ o The internal IP address and/or port number as initially set by the
+ IGD Control Point and stored in the IGD NAT are used to update the
+ corresponding fields in received PCP responses.
+
+ o The external IP address and port number are not altered by the
+ IGD-PCP Interworking Function.
+
+ o The NAT mapping entry in the IGD is updated with the result of
+ each PCP request.
+
+ The lifetime of the mappings instantiated in the IGD SHOULD be the
+ one assigned by the terminating PCP server. In any case, the
+ lifetime MUST NOT be lower than the one assigned by the terminating
+ PCP server.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 11]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+5.6. Creating a Mapping
+
+ Two methods can be used to create a mapping: AddAnyPortMapping() and
+ AddPortMapping().
+
+5.6.1. AddAnyPortMapping()
+
+ When an IGD Control Point issues an AddAnyPortMapping() call, this
+ request is received by the IGD. The request is then relayed to the
+ IGD-PCP IWF, which generates a PCP MAP request (see Section 4.1 for
+ mapping between WANIPConnection and PCP parameters).
+
+ If the IGD-PCP IWF fails to send the MAP request to its PCP server,
+ it follows the behavior defined in Section 5.1.
+
+ Upon receipt of a PCP MAP response from the PCP server, the
+ corresponding UPnP IGD method is returned to the requesting IGD
+ Control Point (the contents of the messages follow the
+ recommendations listed in Section 5.5 or Section 5.4, according to
+ the deployed scenario). A flow example is depicted in Figure 5.
+
+ If a PCP error is received from the PCP server, a corresponding
+ WANIPConnection error code (see Section 4.3) is generated by the
+ IGD-PCP IWF and sent to the requesting IGD Control Point. If a
+ short-lifetime error is returned (e.g., NETWORK_FAILURE,
+ NO_RESOURCES), the PCP IWF MAY resend the same request to the PCP
+ server after 30 seconds. If a negative answer is received, the error
+ is then relayed to the requesting IGD Control Point.
+
+ Discussion: Some applications (e.g., uTorrent, Vuze, eMule) wait
+ 90 seconds or more for a response after sending a UPnP request.
+ If a short-lifetime error occurs, resending the request may lead
+ to a positive response from the PCP server. IGD Control Points
+ are therefore not aware of transient errors.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 12]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ UPnP-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | | |
+ | (1) AddAnyPortMapping() | |
+ | ExternalPort=8080 | |
+ |------------------------>| |
+ | | (2) PCP MAP Request |
+ | |Suggested External Port=8080 |
+ | |---------------------------->|
+ | | |
+ | | (3) PCP MAP Response |
+ | | Assigned External Port=6598 |
+ | |<----------------------------|
+ | (4) AddAnyPortMapping() | |
+ | ReservedPort=6598 | |
+ |<------------------------| |
+
+ Figure 5: Flow Example: AddAnyPortMapping()
+
+5.6.2. AddPortMapping()
+
+ A dedicated option called "PREFER_FAILURE" is defined in [RFC6887] to
+ toggle the behavior in a PCP request message. This option is
+ inserted by the IGD-PCP IWF when issuing its requests to the PCP
+ server only if a specific external port is requested by the IGD
+ Control Point.
+
+ Upon receipt of AddPortMapping() from an IGD Control Point, the
+ IGD-PCP IWF MUST generate a PCP MAP request with all requested
+ mapping information as indicated by the IGD Control Point if no NAT
+ is embedded in the IGD or updated as specified in Section 5.5. In
+ addition, the IGD-PCP IWF MUST insert a PREFER_FAILURE option in the
+ generated PCP request.
+
+ If the IGD-PCP IWF fails to send the MAP request to its PCP server,
+ it follows the behavior defined in Section 5.1.
+
+ If the requested external port is not available, the PCP server will
+ send a CANNOT_PROVIDE_EXTERNAL error response:
+
+ 1. If a short-lifetime error is returned, the IGD-PCP IWF MAY resend
+ the same request to the PCP server after 30 seconds without
+ relaying the error to the IGD Control Point. The IGD-PCP IWF MAY
+ repeat this process until a positive answer is received or some
+ maximum retry limit is reached. When the maximum retry limit is
+ reached, the IGD-PCP IWF relays a negative message to the IGD
+ Control Point with ConflictInMappingEntry as the error code.
+
+
+
+Boucadair, et al. Standards Track [Page 13]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ The maximum retry limit is implementation-specific; its default
+ value is 2.
+
+ 2. If a long-lifetime error is returned, the IGD-PCP IWF relays a
+ negative message to the IGD Control Point with
+ ConflictInMappingEntry as the error code.
+
+ The IGD Control Point may issue a new request with a different
+ requested external port number. This process is typically repeated
+ by the IGD Control Point until a positive answer is received or some
+ maximum retry limit is reached.
+
+ If the PCP server is able to create or renew a mapping with the
+ requested external port, it sends a positive response to the IGD-PCP
+ IWF. Upon receipt of the response from the PCP server, the IGD-PCP
+ IWF stores the returned mapping in its local mapping table and sends
+ the corresponding positive answer to the requesting IGD Control
+ Point. This answer terminates the exchange.
+
+ Figure 6 shows an example of the flow exchange that occurs when the
+ PCP server satisfies the request from the IGD-PCP IWF. Figure 7
+ shows the message exchange when the requested external port is not
+ available.
+
+ UPnP-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | | |
+ | (1) AddPortMapping() | |
+ | ExternalPort=8080 | |
+ |----------------------->| |
+ | | (2) PCP MAP Request |
+ | |Suggested External Port=8080 |
+ | | PREFER_FAILURE |
+ | |---------------------------->|
+ | | |
+ | | (3) PCP MAP Response |
+ | | Assigned External Port=8080 |
+ | |<----------------------------|
+ | (4) AddPortMapping() | |
+ | ExternalPort=8080 | |
+ |<-----------------------| |
+
+ Figure 6: Flow Example (Positive Answer)
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 14]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ UPnP-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | | |
+ | (1) AddPortMapping() | |
+ | ExternalPort=8080 | |
+ |----------------------->| |
+ | | (2) PCP MAP Request |
+ | |Suggested External Port=8080 |
+ | | PREFER_FAILURE |
+ | |---------------------------->|
+ | | (3) PCP MAP Response |
+ | | CANNOT_PROVIDE_EXTERNAL |
+ | |<----------------------------|
+ | (4) Error: | |
+ | ConflictInMappingEntry | |
+ |<-----------------------| |
+ | (5) AddPortMapping() | |
+ | ExternalPort=5485 | |
+ |----------------------->| |
+ | | (6) PCP MAP Request |
+ | |Suggested External Port=5485 |
+ | | PREFER_FAILURE |
+ | |---------------------------->|
+ | | (7) PCP MAP Response |
+ | | CANNOT_PROVIDE_EXTERNAL |
+ | |<----------------------------|
+ | (8) Error: | |
+ | ConflictInMappingEntry | |
+ |<-----------------------| |
+ ....
+ | (a) AddPortMapping() | |
+ | ExternalPort=6591 | |
+ |----------------------->| |
+ | | (b) PCP MAP Request |
+ | |Suggested External Port=6591 |
+ | | PREFER_FAILURE |
+ | |---------------------------->|
+ | | (c) PCP MAP Response |
+ | | CANNOT_PROVIDE_EXTERNAL |
+ | |<----------------------------|
+ | (d) Error: | |
+ | ConflictInMappingEntry | |
+ |<-----------------------| |
+
+ Figure 7: Flow Example (Negative Answer)
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 15]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ Note: According to some experiments, some UPnP 1.0 Control Point
+ implementations, e.g., uTorrent, simply try the same external port
+ a number of times (usually 4 times) and then fail if the port is
+ in use. Also note that some applications use
+ GetSpecificPortMappingEntry() to determine whether a mapping
+ exists.
+
+5.7. Listing One or a Set of Mappings
+
+ In order to list active mappings, an IGD Control Point may issue
+ GetGenericPortMappingEntry(), GetSpecificPortMappingEntry(), or
+ GetListOfPortMappings().
+
+ GetGenericPortMappingEntry() and GetListOfPortMappings() methods MUST
+ NOT be proxied to the PCP server, since a local mapping is maintained
+ by the IGD-PCP IWF.
+
+ Upon receipt of GetSpecificPortMappingEntry() from an IGD Control
+ Point, the IGD-PCP IWF MUST check first to see if the external port
+ number is used by the requesting IGD Control Point. If the external
+ port is already in use by the requesting IGD Control Point, the
+ IGD-PCP IWF MUST send back the mapping entry matching the request.
+ If not, the IGD-PCP IWF MUST relay to the PCP server a MAP request,
+ with short lifetime (e.g., 60 seconds), including a PREFER_FAILURE
+ option. If the IGD-PCP IWF fails to send the MAP request to its PCP
+ server, it follows the behavior defined in Section 5.1. If the
+ requested external port is in use, a PCP error message will be sent
+ by the PCP server to the IGD-PCP IWF indicating
+ CANNOT_PROVIDE_EXTERNAL as the error cause. Then, the IGD-PCP IWF
+ relays a negative message to the IGD Control Point. If the port is
+ not in use, the mapping will be created by the PCP server and a
+ positive response will be sent back to the IGD-PCP IWF. Once
+ received by the IGD-PCP IWF, it MUST relay a negative message to the
+ IGD Control Point indicating NoSuchEntryInArray as the error code so
+ that the IGD Control Point knows the queried mapping doesn't exist.
+
+5.8. Delete One or a Set of Mappings: DeletePortMapping() or
+ DeletePortMappingRange()
+
+ An IGD Control Point requests the deletion of one or a list of
+ mappings by issuing DeletePortMapping() or DeletePortMappingRange().
+
+ In IGD:2, we assume that the IGD applies the appropriate security
+ policies to determine whether a Control Point has the rights to
+ delete one or a set of mappings. When authorization fails, the "606
+ Action Not Authorized" error code is returned to the requesting
+ Control Point.
+
+
+
+
+Boucadair, et al. Standards Track [Page 16]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ When DeletePortMapping() or DeletePortMappingRange() is received by
+ the IGD-PCP IWF, it first checks if the requested mappings to be
+ removed are present in the local mapping table. If no mapping
+ matching the request is found in the local table, an error code is
+ sent back to the IGD Control Point: "714 NoSuchEntryInArray" for
+ DeletePortMapping() or "730 PortMappingNotFound" for
+ DeletePortMappingRange().
+
+ Figure 8 shows an example of an IGD Control Point asking to delete a
+ mapping that is not instantiated in the local table of the IWF.
+
+ UPnP-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | | |
+ | (1) DeletePortMapping() | |
+ |------------------------>| |
+ | | |
+ | (2) Error: | |
+ | NoSuchEntryInArray | |
+ |<------------------------| |
+ | | |
+
+ Figure 8: Local Delete (IGD-PCP IWF)
+
+ If a mapping matches in the local table, a PCP MAP delete request is
+ generated. If no NAT is enabled in the IGD, the IGD-PCP IWF uses the
+ input arguments as included in DeletePortMapping(). If a NAT is
+ enabled in the IGD, the IGD-PCP IWF instead uses the corresponding IP
+ address and port number as assigned by the local NAT.
+
+ If the IGD-PCP IWF fails to send the MAP request to its PCP server,
+ it follows the behavior defined in Section 5.1.
+
+ When a positive answer is received from the PCP server, the IGD-PCP
+ IWF updates its local mapping table (i.e., removes the corresponding
+ entry) and notifies the IGD Control Point of the result of the
+ removal operation. Once the PCP MAP delete request is received by
+ the PCP server, it removes the corresponding entry. A PCP MAP
+ SUCCESS response is sent back if the removal of the corresponding
+ entry was successful; if not, a PCP error message containing the
+ corresponding error cause (see Section 4.3) is sent back to the
+ IGD-PCP IWF.
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 17]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ If DeletePortMappingRange() is used, the IGD-PCP IWF does a lookup in
+ its local mapping table to retrieve individual mappings, instantiated
+ by the requesting Control Point (i.e., authorization checks), that
+ match the signaled port range (i.e., the external port is within the
+ "StartPort" and "EndPort" arguments of DeletePortMappingRange()). If
+ no mapping is found, the "730 PortMappingNotFound" error code is sent
+ to the IGD Control Point (Figure 9). If one or more mappings are
+ found, the IGD-PCP IWF generates individual PCP MAP delete requests
+ corresponding to these mappings (see the example shown in Figure 10).
+
+ The IGD-PCP IWF MAY send a positive answer to the requesting IGD
+ Control Point without waiting to receive all the answers from the PCP
+ server.
+
+ UPnP-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | | |
+ | (1) DeletePortMappingRange() | |
+ | StartPort=8596 | |
+ | EndPort =9000 | |
+ | Protocol =UDP | |
+ |----------------------------->| |
+ | | |
+ | (2) Error: | |
+ | PortMappingNotFound | |
+ |<-----------------------------| |
+ | | |
+
+ Figure 9: Flow Example: Error Encountered when Processing
+ DeletePortMappingRange()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 18]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ Figure 10 illustrates the exchanges that occur when the IWF receives
+ DeletePortMappingRange(). In this example, only two mappings having
+ the external port number in the 6000-6050 range are maintained in the
+ local table. The IWF issues two MAP requests to delete these
+ mappings.
+
+ UPnP-PCP
+ UPnP Control Interworking
+ Point Function PCP Server
+ | | |
+ | (1) DeletePortMappingRange() | |
+ | StartPort=6000 | |
+ | EndPort =6050 | |
+ | Protocol =UDP | |
+ |----------------------------->| |
+ | | |
+ | | (2a) PCP MAP Request |
+ | | Protocol=UDP |
+ | | internal-ip-address |
+ | | internal-port |
+ | | external-ip-address |
+ | | external-port=6030 |
+ | | Requested-lifetime=0 |
+ | |------------------------->|
+ | | |
+ | | (2b) PCP MAP Request |
+ | | Protocol=UDP |
+ | | internal-ip-address |
+ | | internal-port |
+ | | external-ip-address |
+ | | external-port=6045 |
+ | | Requested-lifetime=0 |
+ | |------------------------->|
+ | | |
+ | (3) Positive answer | |
+ |<-----------------------------| |
+ | | |
+
+ Figure 10: Example of DeletePortMappingRange()
+
+5.9. Renewing a Mapping
+
+ Because of the incompatibility of mapping lifetimes between a UPnP
+ IGD and PCP, the IGD-PCP IWF MUST simulate long and even infinite
+ lifetimes. Indeed, for requests having a requested infinite
+ PortMappingLeaseDuration, the IGD-PCP IWF MUST set the Requested
+ Lifetime of the corresponding PCP request to 4294967296. If
+ PortMappingLeaseDuration is not infinite, the IGD-PCP IWF MUST set
+
+
+
+Boucadair, et al. Standards Track [Page 19]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ the Requested Lifetime of the corresponding PCP request to the same
+ value as PortMappingLeaseDuration. Furthermore, the IGD-PCP
+ Interworking Function MUST maintain an additional timer set to the
+ initial requested PortMappingLeaseDuration. Upon receipt of a
+ positive answer from the PCP server, the IGD-PCP IWF relays the
+ corresponding UPnP IGD response to the requesting IGD Control Point
+ with PortMappingLeaseDuration set to the same value as that of the
+ initial request. Then, the IGD-PCP IWF MUST periodically renew the
+ constructed PCP mapping until the expiry of PortMappingLeaseDuration.
+ Responses received when renewing the mapping MUST NOT be relayed to
+ the IGD Control Point.
+
+ If an error is encountered during mapping renewal, the IGD-PCP
+ Interworking Function has no means of informing the IGD Control Point
+ of the error.
+
+5.10. Rapid Recovery
+
+ When the IGD-PCP IWF is co-located with the DHCP server, the state
+ maintained by the IGD-PCP IWF MUST be updated using the state in the
+ local DHCP server. Particularly, if an IP address expires or is
+ released by an internal host, the IGD-PCP IWF MUST delete all the
+ mappings bound to that internal IP address.
+
+ Upon change of the external IP address of the IGD-PCP IWF, the
+ IGD-PCP IWF MAY renew the mappings it maintained. This can be
+ achieved only if a full state table is maintained by the IGD-PCP IWF.
+ If the port quota is not exceeded in the PCP server, the IGD-PCP IWF
+ will receive a new external IP address and port numbers. The IGD-PCP
+ IWF has no means of notifying internal IGD Control Points of the
+ change of the external IP address and port numbers. Stale mappings
+ will be maintained by the PCP server until their lifetime expires.
+
+ Note: If an address change occurs, protocols that are sensitive to
+ address changes (e.g., TCP) will experience disruption.
+
+ [RFC6887] defines a procedure for the PCP server to notify PCP
+ clients of changes related to the mappings it maintains. When an
+ unsolicited ANNOUNCE is received, the IGD-PCP IWF makes one or more
+ MAP requests with the PREFER_FAILURE option to re-install its
+ mappings. If the PCP server cannot create the requested mappings
+ (signaled with the CANNOT_PROVIDE_EXTERNAL error response), the
+ IGD-PCP IWF has no means of notifying internal IGD Control Points of
+ any changes of the external IP address and port numbers.
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 20]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ Unsolicited PCP MAP responses received from a PCP server are handled
+ as any normal MAP response. If a response indicates that the
+ external IP address or port has changed, the IGD-PCP IWF has no means
+ of notifying the internal IGD Control Point of this change.
+
+ Further analysis of PCP failure scenarios for the IGD-PCP
+ Interworking Function are discussed in [PCP-FAILURE].
+
+6. Security Considerations
+
+ IGD:2 access control requirements and authorization levels SHOULD be
+ applied by default [IGD2]. When IGD:2 is used, operation on behalf
+ of a third party SHOULD be allowed only if authentication and
+ authorization are used [IGD2]. When only IGD:1 is available,
+ operation on behalf of a third party SHOULD NOT be allowed.
+
+ This document defines a procedure to create PCP mappings for third-
+ party devices belonging to the same subscriber. The means for
+ preventing a malicious user from creating mappings on behalf of a
+ third party must be enabled as discussed in Section 13.1 of
+ [RFC6887]. In particular, the THIRD_PARTY option MUST NOT be enabled
+ unless the network on which the PCP messages are to be sent is fully
+ trusted -- for example, access control lists (ACLs) installed on the
+ PCP client, the PCP server, and the network between them, so that
+ those ACLs allow only communications from a trusted PCP client to the
+ PCP server.
+
+ An IGD Control Point that issues AddPortMapping(),
+ AddAnyPortMapping(), or GetSpecificPortMappingEntry() requests in a
+ shorter time frame will create a lot of mapping entries on the PCP
+ server. The means for avoiding the exhaustion of port resources
+ (e.g., port quota, as discussed in Section 17.2 of [RFC6887]) SHOULD
+ be enabled.
+
+ The security considerations discussed in [RFC6887] and [Sec_DCP]
+ should be taken into account.
+
+7. Acknowledgments
+
+ The authors would like to thank F. Fontaine, C. Jacquenet, X. Deng,
+ G. Montenegro, D. Thaler, R. Tirumaleswar, P. Selkirk, T. Lemon,
+ V. Gurbani, and P. Yee for their review and comments.
+
+ F. Dupont contributed to previous versions of this document. Thanks
+ go to him for his thorough reviews and contributions.
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 21]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+8. References
+
+8.1. Normative References
+
+ [IGD1] UPnP Forum, "WANIPConnection:1 Service Template
+ Version 1.01", November 2001, <http://upnp.org/specs/
+ gw/UPnP-gw-WANIPConnection-v1-Service.pdf>.
+
+ [IGD2] UPnP Forum, "WANIPConnection:2 Service", September 2010,
+ <http://upnp.org/specs/gw/
+ UPnP-gw-WANIPConnection-v2-Service.pdf>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC6887] Wing, D., Cheshire, S., Boucadair, M., Penno, R., and P.
+ Selkirk, "Port Control Protocol (PCP)", RFC 6887,
+ April 2013.
+
+8.2. Informative References
+
+ [PCP-DESCR-OPT]
+ Boucadair, M., Penno, R., and D. Wing, "PCP Description
+ Option", Work in Progress, May 2013.
+
+ [PCP-DHCP-OPT]
+ Boucadair, M., Penno, R., and D. Wing, "DHCP Options for
+ the Port Control Protocol (PCP)", Work in Progress,
+ March 2013.
+
+ [PCP-FAILURE]
+ Boucadair, M. and R. Penno, "Analysis of Port Control
+ Protocol (PCP) Failure Scenarios", Work in Progress,
+ May 2013.
+
+ [PCP-PROXY]
+ Boucadair, M., Penno, R., and D. Wing, "Port Control
+ Protocol (PCP) Proxy Function", Work in Progress,
+ June 2013.
+
+ [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful
+ NAT64: Network Address and Protocol Translation from IPv6
+ Clients to IPv4 Servers", RFC 6146, April 2011.
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 22]
+
+RFC 6970 UPnP IGD-PCP IWF July 2013
+
+
+ [RFC6333] Durand, A., Droms, R., Woodyatt, J., and Y. Lee,
+ "Dual-Stack Lite Broadband Deployments Following IPv4
+ Exhaustion", RFC 6333, August 2011.
+
+ [Sec_DCP] UPnP Forum, "Device Protection:1 Service", February 2011,
+ <http://upnp.org/specs/gw/
+ UPnP-gw-DeviceProtection-v1-Service.pdf>.
+
+Authors' Addresses
+
+ Mohamed Boucadair
+ France Telecom
+ Rennes 35000
+ France
+
+ EMail: mohamed.boucadair@orange.com
+
+
+ Reinaldo Penno
+ Cisco Systems, Inc.
+ 170 West Tasman Drive
+ San Jose, California 95134
+ USA
+
+ EMail: repenno@cisco.com
+
+
+ Dan Wing
+ Cisco Systems, Inc.
+ 170 West Tasman Drive
+ San Jose, California 95134
+ USA
+
+ EMail: dwing@cisco.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boucadair, et al. Standards Track [Page 23]
+