RFC 6970
Universal Plug and Play (UPnP) Internet Gateway Device - Port Control Protocol Interworking Function (IGD-PCP IWF)
Universal Plug and Play (UPnP) Internet Gateway Device - Port Control Protocol Interworking Function (IGD-PCP IWF) 💖
Okay bestie, this is Part 1 of 5 🎀 It's the intro arc: the title block, the abstract, the boring legal stuff, and the first four sections. It's written by M. Boucadair (France Telecom), R. Penno, and D. Wing (Cisco). It's a Standards Track doc from the IETF, dated July 2013, and its ISSN is 2070-1721 🦋 The title block doesn't list anything it obsoletes or updates.
Abstract
okay so this doc spells out how the UPnP IGD-PCP IWF behaves 🧚 The IWF is supposed to be embedded in Customer Premises (CP) routers. Its whole job is to give you transparent NAT control when a UPnP IGD is on the LAN side and PCP is on the external side of the CP router. main character energy fr 👑
Status of This Memo
this is an Internet Standards Track document 💅
it's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community 🫶 it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 5741 📚
info about the current status of this doc, any errata, and how to give feedback is at http://www.rfc-editor.org/info/rfc6970 🌸
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. ✨
this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they were in effect on the publication date 🙈 please actually read them, because they explain your rights and restrictions. ngl it's the boring part, but it matters. any Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no 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 ....................................22the TOC is basically the map of the whole spec 🗺️ the later parts fill in every section you see here
1. Introduction ✨
okay so the Port Control Protocol (PCP) spec [RFC6887] covers how to build NAT control features that rely on Carrier Grade NAT devices, like a Dual-Stack Lite (DS-Lite) Address Family Transition Router (AFTR) [RFC6333] or NAT64 [RFC6146] 🦋
when a Universal Plug and Play Internet Gateway Device (UPnP IGD) runs on the local network, an interworking function between the UPnP IGD and PCP is required to be embedded in the IGD. Figure 1 shows an example:
UPnP IGD-PCP
UPnP Control Interworking
Point Function PCP Server
| IGD |
| | |
| (1) AddPortMapping() | |
|----------------------->| |
| | (2) PCP MAP Request |
| |-------------------------->|
| | |
Figure 1: Flow Examplethere are two configurations this doc covers 💜
- No NAT function is embedded in the IGD (Section 5.4). This is required, for instance, in DS-Lite or NAT64 deployments.
- The IGD embeds a NAT function (Section 5.5).
the UPnP IGD-PCP Interworking Function (UPnP IGD-PCP IWF) keeps a local mapping table that stores all the active mappings created by internal IGD Control Points 🍓 this design choice limits how many PCP messages get exchanged with the PCP server, which is honestly so smart
deactivating the UPnP IGD-PCP IWF on the IGD and running PCP-only mode is out of scope for this document 🙈
the same goes for how the UPnP IGD-PCP Interworking Function co-exists with a PCP Proxy [PCP-PROXY]. 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] 🔥
2. Acronyms 🌸
this doc uses these 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 Play3. Architecture Model 🧚
quick refresher: Figure 2 shows the architecture model the UPnP Forum adopted [IGD2] 💅 in Figure 2, the UPnP terms mean:
- 'Client' refers to a host located in the local network.
- 'IGD Control Point' is a device using UPnP to control an IGD (Internet Gateway Device).
- 'IGD' is a router supporting a UPnP IGD. It is typically a NAT or a firewall.
- 'Host' is a remote peer reachable in the Internet.
+-------------+
| IGD Control |
| Point |-----+
+-------------+ | +-----+ +------+
+---| | | |
| IGD |-------| Host |
+---| | | |
+-------------+ | +-----+ +------+
| Client |-----+
+-------------+
Figure 2: UPnP IGD Modelthis model breaks down when PCP controls something like a Carrier Grade NAT (aka Provider NAT) while internal hosts keep using a UPnP IGD 😭 for that situation, Figure 3 shows the updated model:
+-------------+
| 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 Modelin the updated model from Figure 3, you can hit one or two levels of NAT on the data path ✨ on top of the Carrier Grade NAT, the IGD might embed a NAT function too (Figure 4):
+-------------+
| IGD Control |
| Point |----+
+-------------+ | +-----+ +--------+ +------+
+---| IGD-| |Provider| |Remote|
| PCP |------| NAT |--<Internet>---| Host |
+---| IWF | | | | |
+-------------+ | +-----+ +--------+ +------+
| Local Host |----+ NAT1 NAT2
+-------------+
Figure 4: Cascaded NAT Scenarioto make UPnP IGD and PCP interwork properly, an interworking function gets embedded in the IGD 🎀 in the Figure 3 model, all the UPnP IGD server-oriented functions, a PCP client [RFC6887], and a UPnP IGD-PCP Interworking Function all live in the IGD. the rest of the doc uses "IGD-PCP IWF" to mean the UPnP IGD-PCP Interworking Function, which includes the PCP client functionality 🫶
without the IGD-PCP IWF, the IGD Control Point would get back an external IP address and port number with limited scope. they can't be used to reach hosts beyond NAT2 (they're assigned by the IGD, not by NAT2 like in Figure 4) 😬
the UPnP IGD-PCP IWF is responsible for building a well-formed PCP message from a received UPnP IGD message, and the other way around too 🦋
4. UPnP IGD-PCP IWF: Overview 🌈
three tables spell out how a UPnP IGD and PCP line up 💖
- Section 4.1 maps the WANIPConnection state variables to PCP parameters
- Section 4.2 focuses on which methods correspond
- Section 4.3 lists the PCP error messages and their matching IGD error messages
fyi, some enhancements got added to WANIPConnection, and they're documented in [IGD2] ✨
4.1. UPnP IGD-PCP: State Variables
okay so bestie, only the UPnP IGD state variables that matter for the IGD-PCP IWF are listed here 🎀
ExternalIPAddress: External IP Address. It's read-only and holds the value from the last PCP response, or the empty string if none has arrived yet ✨. This state is stored on a per-IGD-Control-Point basis.PortMappingNumberOfEntries: Managed locally by the UPnP IGD-PCP IWF 🧚PortMappingEnabled: lowkey the most dramatic one 💀. PCP does not support deactivating the dynamic NAT mapping, since PCP's whole goal is easing the traversal of Carrier Grade NAT 🦋. Supporting that per-subscriber function may overload the Carrier Grade NAT. Only "1" is allowed, so 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 gets remapped to the IGD maximum of 604800 seconds [IGD2]. PCP allows a maximum value of 4294967296 seconds. The UPnP IGD-PCP IWF simulates long and even infinite lifetimes using renewals (see Section 5.9), and what it does when a renewal fails is currently undefined (see Section 5.9). 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, meaning the state doesn't have to survive resets or reboots. The UPnP IGD-PCP Interworking Function MUST support IGD:2 behavior 💅.RemoteHost: Remote Peer IP Address. IGD:2 allows a domain name, which has to be resolved to an IP address. It's 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. IGD:2 allows a domain name, which has to be resolved to an IP address. It's 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
both the IGD:1 and IGD:2 methods that apply to the UPnP IGD-PCP Interworking Function are listed here, so you've got everything in one spot 🌸
GetGenericPortMappingEntry(): this request is not relayed to the PCP server. The IGD-PCP IWF keeps a list of the active mappings instantiated in the PCP server by internal hosts. See Section 5.7 for more info.GetSpecificPortMappingEntry(): MAP with PREFER_FAILURE option. This request gets 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. The 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 on TCP/9 or UDP/9, or some other port). Be careful though, because once that mapping expires, a later implicit or explicit dynamic mapping might map 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 IWF maintains a list of active mappings instantiated in the PCP server, and it handles this request locally 🧠.
4.3. UPnP IGD-PCP: Errors
this section lists the PCP error codes and their matching UPnP IGD codes 🚨. Error codes that are specific to IGD:2 are tagged accordingly.
1 UNSUPP_VERSION:501 "ActionFailed"2 NOT_AUTHORIZED: IGD:1718 "ConflictInMappingEntry"/ IGD:2606 "Action not authorized"3 MALFORMED_REQUEST:501 "ActionFailed"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 that situation 😬.5 UNSUPP_OPTION:501 "ActionFailed". You can get this error code if PREFER_FAILURE isn't supported on the PCP server. PREFER_FAILURE isn't mandatory to support, but AddPortMapping() can't be implemented without it.6 MALFORMED_OPTION:501 "ActionFailed"7 NETWORK_FAILURE:501 "ActionFailed"8 NO_RESOURCES: IGD:1501 "ActionFailed"/ IGD:2728 "NoPortMapsAvailable". This can't be distinguished from USER_EX_QUOTA.9 UNSUPP_PROTOCOL:501 "ActionFailed"10 USER_EX_QUOTA: IGD:1501 "ActionFailed"/ IGD:2728 "NoPortMapsAvailable". This can't be distinguished from NO_RESOURCES.11 CANNOT_PROVIDE_EXTERNAL:718 "ConflictInMappingEntry"(see Section 5.6.2) or714 "NoSuchEntryInArray"(see Section 5.8).12 ADDRESS_MISMATCH:501 "ActionFailed"13 EXCESSIVE_REMOTE_PEERS:501 "ActionFailed"
5. Specification of the IGD-PCP IWF ✨
this is the main event, bestie 👑. This section covers scenarios both with and 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]). It behaves as a PCP client when it talks to provisioned PCP server(s) 🦋.
If no IPv4 address or IPv6 prefix is assigned to the IGD, or the IGD can't figure out whether it should contact an upstream PCP server, the IGD-PCP Interworking Function MUST NOT be invoked 🙅♀️.
If the IGD decides it should talk to 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 when the IGD-PCP IWF fails to establish communication with that PCP server. Note that the IGD-PCP IWF goes on to PCP message validation and retransmission the same way as any PCP client [RFC6887] 💅.
5.2. Control of the Firewall
to set up security policies for inbound and outbound traffic, a UPnP IGD can be used to control a local firewall engine. So no IGD-PCP IWF is needed for that purpose 🧱.
Using 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 💾.
When a PCP MAP response comes in 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 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 there's no NAT embedded in the IGD, the contents of received WANIPConnection and PCP messages are not altered by the IGD-PCP IWF. (In other words, the contents of WANIPConnection messages are mapped to PCP messages and mapped back, according to Section 4.1 🔁.)
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 that belong 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 one, 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 the IGD-PCP IWF sends to the PCP server MUST reflect the mapping information as enforced in the first NAT. In particular, the internal IP address and/or port number of the requests are replaced with the IP address and/or port number assigned by the NAT of the IGD. On 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:
- 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.
- The external IP address and port number are not altered by the IGD-PCP Interworking Function.
- 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 ⏳💜.
5.6. Creating a Mapping
okay, two methods can be used to create a mapping: AddAnyPortMapping() and AddPortMapping() 🦋✨.
5.6.1. AddAnyPortMapping() ✨
Okay so when an IGD Control Point sends an AddAnyPortMapping() call, the IGD catches it and passes it to the IGD-PCP IWF 💅 The IWF then builds a PCP MAP request. (For how WANIPConnection parameters line up with PCP parameters, check Section 4.1 🎀)
If the IGD-PCP IWF can't send the MAP request to its PCP server, it follows the behavior in Section 5.1 🫶
When the MAP response comes back from the PCP server, the matching UPnP IGD method goes back to the requesting IGD Control Point. The message contents follow the recommendations in Section 5.5 or Section 5.4, depending on which deployment scenario you're in 🌸 Figure 5 shows the whole flow ✨
If the PCP server sends back a PCP error, the IGD-PCP IWF turns it into a matching WANIPConnection error code (see Section 4.3) and sends that to the requesting IGD Control Point 😭 If it's a short-lifetime error (like NETWORK_FAILURE or NO_RESOURCES), the PCP IWF MAY resend the same request to the PCP server after 30 seconds. If a negative answer comes back, then the error gets relayed to the requesting IGD Control Point 🦋
Discussion: Some apps (uTorrent, Vuze, eMule) wait 90 seconds or more for a response after sending a UPnP request. If a short-lifetime error happens, resending the request might lead to a positive response from the PCP server. So IGD Control Points aren't aware of transient errors at all 🙈
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() 💖
Okay this one's giving main character energy 👑 [RFC6887] defines a special option called PREFER_FAILURE that toggles behavior in a PCP request message. The IGD-PCP IWF only inserts this option into its requests to the PCP server when the IGD Control Point asks for a specific external port 🎀
When AddPortMapping() comes in from an IGD Control Point, the IGD-PCP IWF MUST generate a PCP MAP request with all of the mapping info the IGD Control Point asked for, if no NAT is embedded in the IGD. If there is a NAT embedded in the IGD, the request gets updated as described in Section 5.5 instead 🔥 On top of that, the IGD-PCP IWF MUST insert a PREFER_FAILURE option into the request it generates ✨
If the IGD-PCP IWF can't send the MAP request to its PCP server, it follows the behavior in Section 5.1 🫶
If the requested external port isn't available, the PCP server sends back a CANNOT_PROVIDE_EXTERNAL error response 💀 Here's what happens next:
- If a short-lifetime error comes back, the IGD-PCP IWF MAY resend the same request to the PCP server after 30 seconds, and it doesn't relay the error to the IGD Control Point. The IGD-PCP IWF MAY keep repeating this until it gets a positive answer or hits some maximum retry limit. Once that limit is reached, the IGD-PCP IWF relays a negative message to the IGD Control Point with
ConflictInMappingEntryas the error code.
The maximum retry limit is implementation-specific, and its default value is 2 🌈
- If a long-lifetime error comes back, the IGD-PCP IWF relays a negative message to the IGD Control Point with
ConflictInMappingEntryas the error code 😭
The IGD Control Point can send a new request with a different requested external port number. Usually the IGD Control Point keeps doing this until it gets a positive answer or hits some maximum retry limit 🍓
If the PCP server can create or renew a mapping with the requested external port, it sends a positive response to the IGD-PCP IWF. Once the IGD-PCP IWF gets that response, it stores the returned mapping in its local mapping table and sends the matching positive answer to the requesting IGD Control Point. That answer ends the exchange ✨
Figure 6 shows the flow when the PCP server says yes to the IGD-PCP IWF's request. Figure 7 shows the message exchange when the requested external port isn't 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) 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)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 🧚
Okay so to list active mappings, an IGD Control Point can send GetGenericPortMappingEntry(), GetSpecificPortMappingEntry(), or GetListOfPortMappings() 📋
GetGenericPortMappingEntry() and GetListOfPortMappings() MUST NOT be proxied to the PCP server, because the IGD-PCP IWF keeps a local mapping of its own 🙅♀️
When GetSpecificPortMappingEntry() comes in from an IGD Control Point, the IGD-PCP IWF MUST check first whether the external port number is already used by the requesting IGD Control Point. If the requesting IGD Control Point already has that external port in use, the IGD-PCP IWF MUST send back the mapping entry that matches the request 💜 If it doesn't, the IGD-PCP IWF MUST relay a MAP request to the PCP server with a short lifetime (e.g., 60 seconds), including a PREFER_FAILURE option ✨ If the IGD-PCP IWF can't send the MAP request to its PCP server, it follows the behavior in Section 5.1 🫶
If the requested external port is in use, the PCP server sends a PCP error message to the IGD-PCP IWF saying CANNOT_PROVIDE_EXTERNAL as the error cause. The IGD-PCP IWF then relays a negative message to the IGD Control Point 😭 If the port isn't in use, the PCP server creates the mapping and sends a positive response back to the IGD-PCP IWF. Once the IGD-PCP IWF receives that, it MUST relay a negative message to the IGD Control Point with NoSuchEntryInArray as the error code, so the IGD Control Point knows the queried mapping doesn't exist 🌸
5.8. Delete One or a Set of Mappings: DeletePortMapping() or DeletePortMappingRange() ✨
Okay so an IGD Control Point is the one asking for deletion, either of one mapping or a whole list of them, by calling DeletePortMapping() or DeletePortMappingRange(). 💅
In IGD:2, we assume the IGD applies the right security policies to figure out whether a Control Point actually has the rights to delete mappings. If authorization fails, the Control Point gets the 606 Action Not Authorized error. Not cute. 🙅♀️
When the IGD-PCP IWF gets DeletePortMapping() or DeletePortMappingRange(), it first checks whether the mappings being removed are even in its local mapping table. If nothing matches, it sends an error back to the IGD Control Point: 714 NoSuchEntryInArray for DeletePortMapping(), or 730 PortMappingNotFound for DeletePortMappingRange(). 🥲
Figure 8 shows an IGD Control Point trying to delete a mapping that isn't in the IWF's local table:
UPnP-PCP
UPnP Control Interworking
Point Function PCP Server
| | |
| (1) DeletePortMapping() | |
|------------------------>| |
| | |
| (2) Error: | |
| NoSuchEntryInArray | |
|<------------------------| |
| | |Figure 8: Local Delete (IGD-PCP IWF)
If a mapping does match in the local table, a PCP MAP delete request gets generated. If no NAT is enabled in the IGD, the IGD-PCP IWF uses the input arguments exactly as they came in DeletePortMapping(). If NAT is enabled in the IGD, it uses the IP address and port number that the local NAT assigned instead. 🧚
If the IGD-PCP IWF can't send the MAP request to its PCP server, it follows the behavior defined in Section 5.1. 🙏
When a positive answer comes back from the PCP server, the IGD-PCP IWF updates its local mapping table (aka it removes the matching entry) and tells the IGD Control Point how the removal went. On the PCP server's side, once the PCP MAP delete request arrives, the server removes the corresponding entry. It sends back a PCP MAP SUCCESS response if the removal worked. If it didn't, it sends a PCP error message with the corresponding error cause (see Section 4.3) back to the IGD-PCP IWF. 💌
If DeletePortMappingRange() is used, the IGD-PCP IWF searches its local mapping table for individual mappings that match the signaled port range. Those are the mappings the requesting Control Point instantiated, so this is where the authorization checks come in 🔐. A match means 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 for them (see the example 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()
Figure 10 walks through what happens when the IWF receives DeletePortMappingRange(). In this example, only two mappings with external port numbers in the 6000-6050 range are in the local table, so the IWF issues two MAP requests to delete them. 🦋
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 🔁
Okay this one's a little dramatic 😭. UPnP IGDs and PCP handle mapping lifetimes differently, so the IGD-PCP IWF MUST simulate long and even infinite lifetimes. For requests with 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 the Requested Lifetime of the corresponding PCP request to the same value as PortMappingLeaseDuration. On top of that, the IGD-PCP Interworking Function MUST maintain an additional timer set to the initial requested PortMappingLeaseDuration. When a positive answer comes from the PCP server, the IWF relays the corresponding UPnP IGD response to the requesting IGD Control Point, with PortMappingLeaseDuration set to the same value as 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. Specifically, 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 only be done if the IGD-PCP IWF maintains a full state table. 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. 📣
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.
Bestie, this next part is serious. 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 🌸
okay bestie, big thank-you energy time 🫶 The authors wanna shout out F. Fontaine, C. Jacquenet, X. Deng, G. Montenegro, D. Thaler, R. Tirumaleswar, P. Selkirk, T. Lemon, V. Gurbani, and P. Yee for reviewing the doc and dropping their comments. These people are literally the reason this spec is so solid 💜
F. Dupont also contributed to earlier versions of this document. He did super thorough reviews and contributions, so thank you to him too 👑✨
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.[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 🦋
Here are the authors' contact details, copied exactly so you can reach them 💌
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📦 where this page comes from
- ietf: rfc6970 2013-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms