idnits 2.17.1 draft-ietf-pcp-upnp-igd-interworking-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 26, 2013) is 4017 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'IGD1' -- Possible downref: Non-RFC (?) normative reference: ref. 'IGD2' == Outdated reference: A later version (-06) exists of draft-boucadair-pcp-failure-05 == Outdated reference: A later version (-05) exists of draft-ietf-pcp-description-option-00 == Outdated reference: A later version (-13) exists of draft-ietf-pcp-dhcp-07 == Outdated reference: A later version (-09) exists of draft-ietf-pcp-proxy-02 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 PCP Working Group M. Boucadair 3 Internet-Draft France Telecom 4 Intended status: Standards Track R. Penno 5 Expires: October 28, 2013 D. Wing 6 Cisco 7 April 26, 2013 9 Universal Plug and Play (UPnP) Internet Gateway Device (IGD)-Port 10 Control Protocol (PCP) Interworking Function 11 draft-ietf-pcp-upnp-igd-interworking-10 13 Abstract 15 This document specifies the behavior of the UPnP IGD (Internet 16 Gateway Device)/PCP Interworking Function. A UPnP IGD-PCP 17 Interworking Function (IGD-PCP IWF) is required to be embedded in CP 18 (Customer Premises) routers to allow for transparent NAT control in 19 environments where UPnP IGD is used on the LAN side and PCP on the 20 external side of the CP router. 22 Requirements Language 24 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 25 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 26 document are to be interpreted as described in RFC 2119 [RFC2119]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on October 28, 2013. 45 Copyright Notice 47 Copyright (c) 2013 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 2. Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Architecture Model . . . . . . . . . . . . . . . . . . . . . 4 65 4. UPnP IGD-PCP IWF: Overview . . . . . . . . . . . . . . . . . 5 66 4.1. UPnP IGD-PCP: State Variables . . . . . . . . . . . . . . 6 67 4.2. IGD-PCP: Methods . . . . . . . . . . . . . . . . . . . . 7 68 4.3. UPnP IGD-PCP: Errors . . . . . . . . . . . . . . . . . . 8 69 5. Specification of the IGD-PCP IWF . . . . . . . . . . . . . . 9 70 5.1. PCP Server Discovery . . . . . . . . . . . . . . . . . . 9 71 5.2. Control of the Firewall . . . . . . . . . . . . . . . . . 9 72 5.3. Port Mapping Table . . . . . . . . . . . . . . . . . . . 10 73 5.4. Interworking Function Without NAT in the IGD . . . . . . 10 74 5.5. NAT Embedded in the IGD . . . . . . . . . . . . . . . . . 10 75 5.6. Creating a Mapping . . . . . . . . . . . . . . . . . . . 11 76 5.6.1. AddAnyPortMapping() . . . . . . . . . . . . . . . . . 11 77 5.6.2. AddPortMapping() . . . . . . . . . . . . . . . . . . 12 78 5.7. Listing One or a Set of Mappings . . . . . . . . . . . . 15 79 5.8. Delete One or a Set of Mappings: DeletePortMapping() or 80 DeletePortMappingRange() . . . . . . . . . . . . . . . . 15 81 5.9. Renewing a Mapping . . . . . . . . . . . . . . . . . . . 18 82 5.10. Rapid Recovery . . . . . . . . . . . . . . . . . . . . . 19 83 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 84 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 85 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 87 9.1. Normative References . . . . . . . . . . . . . . . . . . 21 88 9.2. Informative References . . . . . . . . . . . . . . . . . 21 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 91 1. Introduction 93 PCP [I-D.ietf-pcp-base] discusses the implementation of NAT control 94 features that rely upon Carrier Grade NAT devices such as a DS-Lite 95 AFTR [RFC6333] or NAT64 [RFC6146]. Nevertheless, in environments 96 where UPnP IGD (Internet Gateway Device) is used in the local 97 network, an interworking function between UPnP IGD and PCP is 98 required to be embedded in the IGD (see the example illustrated in 99 Figure 1). 101 UPnP IGD-PCP 102 UPnP Control Interworking 103 Point Function PCP Server 104 | IGD | 105 | | | 106 | (1) AddPortMapping | | 107 |--------------------->| | 108 | | (2) PCP MAP Request | 109 | |-------------------------->| 110 | | | 112 Figure 1: Flow Example 114 Two configurations are considered within this document: 116 o No NAT function is embedded in the IGD (Section 5.4). This is 117 required for instance in DS-Lite or NAT64 deployments; 119 o The IGD embeds a NAT function (Section 5.5). 121 The UPnP IGD-PCP Interworking Function (UPnP IGD-PCP IWF) maintains a 122 local mapping table that stores all active mappings constructed by 123 internal IGD Control Points. This design choice restricts the amount 124 of PCP messages to be exchanged with the PCP Server. 126 Triggers for deactivating the UPnP IGD-PCP IWF from the IGD and 127 relying on a PCP-only mode are out of scope of this document. 129 Considerations related to co-existence of the UPnP IGD-PCP 130 Interworking Function and a PCP Proxy [I-D.ietf-pcp-proxy] are out of 131 scope. 133 2. Acronyms 135 This document makes use of the following abbreviations: 137 DS-Lite - Dual-Stack Lite 138 IGD - Internet Gateway Device 139 IGD:1 - UPnP Forum's nomenclature for version 1 of IGD [IGD1] 140 IGD:2 - UPnP Forum's nomenclature for version 2 of IGD [IGD2] 141 IWF - Interworking Function 142 NAT - Network Address Translation 143 PCP - Port Control Protocol 144 UPnP - Universal Plug and Play 146 3. Architecture Model 148 As a reminder, Figure 2 illustrates the architecture model as adopted 149 by the UPnP Forum [IGD2]. In Figure 2, the following UPnP 150 terminology is used: 152 o 'Client' refers to a host located in the local network. 154 o 'IGD Control Point' is a device using UPnP to control an IGD 155 (Internet Gateway Device). 157 o 'IGD' is a router supporting UPnP IGD. It is typically a NAT or a 158 firewall. 160 o 'Host' is a remote peer reachable in the Internet. 162 +-------------+ 163 | IGD Control | 164 | Point |-----+ 165 +-------------+ | +-----+ +------+ 166 +---| | | | 167 | IGD |-------| Host | 168 +---| | | | 169 +-------------+ | +-----+ +------+ 170 | Client |-----+ 171 +-------------+ 173 Figure 2: UPnP IGD Model 175 This model is not valid when PCP is used to control for instance a 176 Carrier Grade NAT (a.k.a., Provider NAT) while internal hosts 177 continue to use UPnP IGD. In such scenarios, Figure 3 shows the 178 updated model. 180 +-------------+ 181 | IGD Control | 182 | Point |----+ 183 +-------------+ | +-----+ +--------+ +------+ 184 +---| IGD-| |Provider| |Remote| 185 | PCP |------| NAT |-----| Host | 186 +---| IWF | | | | | 187 +-------------+ | +-----+ +--------+ +------+ 188 | Local Host |----+ 189 +-------------+ 190 LAN Side External Side 191 <======UPnP IGD==============><=====PCP=====> 192 Figure 3: UPnP IGD-PCP Interworking Model 194 In the updated model depicted in Figure 3, one or two levels of NAT 195 can be encountered in the data path. Indeed, in addition to the 196 Carrier Grade NAT, the IGD may embed a NAT function (Figure 4). 198 +-------------+ 199 | IGD Control | 200 | Point |----+ 201 +-------------+ | +-----+ +--------+ +------+ 202 +---| IGD-| |Provider| |Remote| 203 | PCP |------| NAT |-----| Host | 204 +---| IWF | | | | | 205 +-------------+ | +-----+ +--------+ +------+ 206 | Local Host |----+ NAT1 NAT2 207 +-------------+ 209 Figure 4: Cascaded NAT scenario 211 To ensure successful interworking between UPnP IGD and PCP, an 212 interworking function is embedded in the IGD. In the model defined 213 in Figure 3, all UPnP IGD server-oriented functions, a PCP Client 214 [I-D.ietf-pcp-base] and a UPnP IGD-PCP Interworking Function are 215 embedded in the IGD. In the rest of the document, IGD-PCP IWF refers 216 the UPnP IGD-PCP Interworking Function, which includes PCP Client 217 functionality. 219 Without the involvement of the IGD-PCP IWF, the IGD Control Point 220 would retrieve an external IP address and port number having a 221 limited scope and which cannot be used to communicate with hosts 222 located beyond NAT2 (i.e., assigned by the IGD and not the ones 223 assigned by NAT2 in Figure 4). 225 UPnP IGD-PCP IWF is responsible for generating a well-formed PCP 226 message from a received UPnP IGD message, and vice versa. 228 4. UPnP IGD-PCP IWF: Overview 230 Three tables are provided to specify the correspondence between UPnP 231 IGD and PCP: 233 (1) Section 4.1 provides the mapping between WANIPConnection State 234 Variables and PCP parameters; 236 (2) Section 4.2 focuses on the correspondence between supported 237 methods; 239 (3) Section 4.3 lists the PCP error messages and their corresponding 240 IGD ones. 242 Note that some enhancements have been integrated in WANIPConnection 243 as documented in [IGD2]. 245 4.1. UPnP IGD-PCP: State Variables 247 Below are listed only the UPnP IGD state variables applicable to the 248 IGD-PCP IWF: 250 ExternalIPAddress: External IP Address 251 Read-only variable with the value from the last PCP response or 252 the empty string if none was received yet. This state is stored 253 on a per IGD Control Point basis. 255 PortMappingNumberOfEntries: Managed locally by the UPnP IGD-PCP IWF. 257 PortMappingEnabled: 258 PCP does not support deactivating the dynamic NAT mapping since 259 the initial goal of PCP is to ease the traversal of Carrier Grade 260 NAT. Supporting such per-subscriber function may overload the 261 Carrier Grade NAT. 262 Only "1" is allowed: i.e., the UPnP IGD-PCP Interworking Function 263 MUST send back an error if a value different from 1 is signaled. 265 PortMappingLeaseDuration: Requested Mapping Lifetime 266 In IGD:1 [IGD1] the value 0 means infinite, in IGD:2 it is 267 remapped to the IGD maximum of 604800 seconds [IGD2]. PCP allows 268 for a maximum value of 4294967296 seconds. 269 The UPnP IGD-PCP Interworking Function simulates long and even 270 infinite lifetimes using renewals (see Section 5.9). The behavior 271 of the UPnP IGD-PCP IWF in the case of a failing renewal is 272 currently undefined (see Section 5.9). 273 IGD:1 doesn't define the behavior in the case of state loss, IGD:2 274 doesn't require to keep state in stable storage, i.e., to allow 275 the state to survive resets/reboots. The UPnP IGD-PCP 276 Interworking Function MUST support IGD:2 behavior. 278 RemoteHost: Remote Peer IP Address 279 Note that IGD:2 allows a domain name, which has to be resolved to 280 an IP address. Mapped to the Remote Peer IP Address field of 281 FILTER option. 283 ExternalPort: External Port Number 284 Mapped to the Suggested External Port in MAP messages. 286 InternalPort: Internal Port Number 287 Mapped to the Internal Port field in MAP messages. 289 PortMappingProtocol: Protocol 290 Mapped to the Protocol field in MAP messages. Note that UPnP IGD 291 only supports TCP and UDP. 293 InternalClient: Internal IP Address 294 Note that IGD:2 allows a domain name, which has to be resolved to 295 an IP address. Mapped to the Internal IP Address field of 296 THIRD_PARTY option. 298 PortMappingDescription: Not supported in base PCP. 299 If the local PCP Client supports a PCP Option to convey the 300 description (e.g., [I-D.ietf-pcp-description-option]), this option 301 SHOULD be used to relay the mapping description. 303 SystemUpdateID (IGD:2 only): Managed locally by the UPnP IGD-PCP 304 IWF. 306 A_ARG_TYPE_PortListing (IGD:2 only): Managed locally by the UPnP 307 IGD-PCP IWF. 309 4.2. IGD-PCP: Methods 311 Both IGD:1 and IGD:2 methods applicable to the UPnP IGD-PCP 312 Interworking Function are listed here. 314 GetGenericPortMappingEntry: This request is not relayed to the PCP 315 Server. 316 IGD-PCP Interworking Function maintains a list of active mappings 317 instantiated in the PCP Server by internal hosts. See Section 5.7 318 for more information. 320 GetSpecificPortMappingEntry: MAP with PREFER_FAILURE Option 321 This request is relayed to the PCP Server by issuing a MAP request 322 with the PREFER_FAILURE Option. It is RECOMMENDED to use a short 323 lifetime (e.g., 60 seconds). 325 AddPortMapping: MAP 326 See Section 5.6.2. 328 AddAnyPortMapping (IGD:2 only): MAP 329 See Section 5.6.1. 331 DeletePortMapping: MAP with Requested Lifetime set to 0. 332 See Section 5.8. 334 DeletePortMappingRange (IGD:2 only): MAP with Requested Lifetime set 335 to 0. 336 Individual requests are issued by the IGD-PCP IWF. See 337 Section 5.8 for more details. 339 GetExternalIPAddress: MAP 340 This can be learned from any active mapping. If there are no 341 active mappings, the IGD-PCP IWF MAY request a short-lived mapping 342 (e.g., to the Discard service (TCP/9 or UDP/9) or some other 343 port). However, once that mapping expires a subsequent implicit 344 or explicit dynamic mapping might be mapped to a different 345 external IP address. See section 11.6 of [I-D.ietf-pcp-base] for 346 more discussion. 348 GetListOfPortMappings: See Section 5.7 for more information. 349 The IGD-PCP Interworking Function maintains a list of active 350 mappings instantiated in the PCP Server. The IGD-PCP Interworking 351 Function handles this request locally. 353 4.3. UPnP IGD-PCP: Errors 355 This section lists PCP errors codes and the corresponding UPnP IGD 356 ones. Error codes specific to IGD:2 are tagged accordingly. 358 1 UNSUPP_VERSION: 501 "ActionFailed" 360 2 NOT_AUTHORIZED: IGD:1 718 "ConflictInMappingEntry" / IGD:2 606 361 "Action not authorized" 363 3 MALFORMED_REQUEST: 501 "ActionFailed" 365 4 UNSUPP_OPCODE: 501 "ActionFailed" 366 [I-D.ietf-pcp-base] allows the PCP server to be configured to 367 disable support for the MAP opcode, but the IGD-PCP IWF cannot 368 work in this situation. 370 5 UNSUPP_OPTION: 501 "ActionFailed" 371 This error code can be received if PREFER_FAILURE is not supported 372 on the PCP server. Note that PREFER_FAILURE is not mandatory to 373 support, but AddPortMapping() cannot be implemented without it. 375 6 MALFORMED_OPTION: 501 "ActionFailed" 377 7 NETWORK_FAILURE: 501 "ActionFailed" 379 8 NO_RESOURCES: IGD:1 501 "ActionFailed" / IGD:2 728 380 "NoPortMapsAvailable" 381 Cannot be distinguished from USER_EX_QUOTA. 383 9 UNSUPP_PROTOCOL: 501 "ActionFailed" 385 10 USER_EX_QUOTA: IGD:1 501 "ActionFailed" / IGD:2 728 386 "NoPortMapsAvailable" 387 Cannot be distinguished from NO_RESOURCES. 389 11 CANNOT_PROVIDE_EXTERNAL: 718 "ConflictInMappingEntry" (see 390 Section 5.7.2) or 714 "NoSuchEntryInArray" (see Section 5.8). 392 12 ADDRESS_MISMATCH: 501 "ActionFailed" 394 13 EXCESSIVE_REMOTE_PEERS: 501 "ActionFailed" 396 5. Specification of the IGD-PCP IWF 398 This section covers the scenarios with or without NAT in the IGD. 400 This specification assumes the PCP Server is configured to accept the 401 MAP OpCode. 403 The IGD-PCP IWF handles the "Mapping Nonce" the same way as any PCP 404 Client [I-D.ietf-pcp-base]. 406 5.1. PCP Server Discovery 408 The IGD-PCP IWF implements one of the discovery methods identified in 409 [I-D.ietf-pcp-base] (e.g., DHCP [I-D.ietf-pcp-dhcp]). The IGD-PCP 410 Interworking Function behaves as a PCP Client when communicating with 411 provisioned PCP Server(s). 413 If no IPv4 address / IPv6 prefix is assigned to the IGD or the IGD is 414 unable to determine whether it should contact an upstream PCP Server, 415 the IGD-PCP Interworking Function MUST NOT be invoked. 417 If the IGD determines that it should establish communication with an 418 upstream PCP server (e.g., because of DHCP configuration or having 419 previously been talking to a PCP server), a "501 ActionFailed" error 420 message is returned to the requesting IGD Control Point in case the 421 IGD-PCP IWF fails to establish communication with that PCP Server. 422 Note, the IGD-PCP IWF proceeds to PCP messages validation and 423 retransmission the same way as any PCP Client [I-D.ietf-pcp-base]. 425 5.2. Control of the Firewall 427 In order to configure security policies to be applied to inbound and 428 outbound traffic, UPnP IGD can be used to control a local firewall 429 engine. No IGD-PCP IWF is therefore required for that purpose. 431 The use of IGD-PCP IWF to control an upstream PCP-controlled firewall 432 is out of scope of this document. 434 5.3. Port Mapping Table 436 The IGD-PCP IWF MUST store locally all the mappings instantiated by 437 internal IGD Control Points in the PCP Server. All mappings SHOULD 438 be stored in permanent storage. 440 Upon receipt of a PCP MAP Response from the PCP Server, the IGD-PCP 441 Interworking Function MUST extract the enclosed mapping and MUST 442 store it in the local mapping table. The local mapping table is an 443 image of the mapping table as maintained by the PCP Server for a 444 given subscriber. 446 Each mapping entry stored in the local mapping table is associated 447 with a lifetime as discussed in [I-D.ietf-pcp-base]. Additional 448 considerations specific to the IGD-PCP Interworking Function are 449 discussed in Section 5.9. 451 5.4. Interworking Function Without NAT in the IGD 453 When no NAT is embedded in the IGD, the content of received 454 WANIPConnection and PCP messages is not altered by the IGD-PCP 455 Interworking Function (i.e., the content of WANIPConnection messages 456 are mapped to PCP messages (and mapped back) according to 457 Section 4.1). 459 5.5. NAT Embedded in the IGD 461 When NAT is embedded in the IGD, the IGD-PCP IWF updates the content 462 of mapping messages received from the IGD Control Point. These 463 messages will contain an IP address and/or port number which belong 464 to an internal host. The IGD-PCP IWF MUST update such messages with 465 the IP address and/or port number belonging to the external interface 466 of the IGD (i.e., after the NAT1 operation in Figure 4). 468 The IGD-PCP IWF intercepts all WANIPConnection messages issued by the 469 IGD Control Point. For each such message, the IGD-PCP IWF then 470 generates one or more corresponding requests (see Section 4.1, 471 Section 4.2 and Section 4.3) and sends them to the provisioned PCP 472 Server. 474 Each request sent by the IGD-PCP IWF to the PCP Server MUST reflect 475 the mapping information as enforced in the first NAT. Particularly, 476 the internal IP address and/or port number of the requests are 477 replaced with the IP address and/or port number as assigned by the 478 NAT of the IGD. For the reverse path, the IGD-PCP IWF intercepts PCP 479 response messages and generates WANIPConnection response messages. 480 The content of the generated WANIPConnection response messages are 481 set as follows: 483 o The internal IP address and/or port number as initially set by the 484 IGD Control Point and stored in the IGD NAT are used to update the 485 corresponding fields in received PCP responses. 487 o The external IP and port number are not altered by the IGD-PCP 488 Interworking Function. 490 o The NAT mapping entry in the IGD is updated with the result of PCP 491 request. 493 The lifetime of the mappings instantiated in the IGD SHOULD be the 494 one assigned by the terminating PCP Server. In any case, the 495 lifetime MUST NOT be lower than the one assigned by the terminating 496 PCP Server. 498 5.6. Creating a Mapping 500 Two methods can be used to create a mapping: AddAnyPortMapping() or 501 AddPortMapping(). 503 5.6.1. AddAnyPortMapping() 505 When a IGD Control Point issues an AddAnyPortMapping(), this request 506 is received by the IGD. The request is then relayed to the IGD-PCP 507 IWF which generates a PCP MAP request (see Section 4.1 for mapping 508 between WANIPConnection and PCP parameters). 510 If the IGD-PCP IWF fails to send the MAP request to its PCP Server, 511 it follows the behavior defined in Section 5.1. 513 Upon receipt of a PCP MAP response from the PCP Server, the 514 corresponding UPnP IGD method is returned to the requesting IGD 515 Control Point (the content of the messages follows the 516 recommendations listed in Section 5.5 or Section 5.4 according to the 517 deployed scenario). A flow example is depicted in Figure 5. 519 If a PCP error is received from the PCP Server, a corresponding 520 WANIPConnection error code (see Section 4.3) is generated by the IGD- 521 PCP IWF and sent to the requesting IGD Control Point. If a short 522 lifetime error is returned (e.g., NETWORK_FAILURE, NO_RESOURCES), the 523 PCP IWF MAY resend the same request to the PCP Server after 30 524 seconds. If a negative answer is received, the error is then relayed 525 to the requesting IGD Control Point. 527 Discussion: Some applications (e.g., uTorrent, Vuze, eMule) wait 528 90 seconds or more for a response after sending an UPnP request. 529 If a short lifetime error occurs, resending the request may lead 530 to a positive response from the PCP server. IGD Control Points 531 are therefore not aware of transient errors. 533 UPnP-PCP 534 UPnP Control Interworking 535 Point Function PCP Server 536 | | | 537 |(1) AddAnyPortMapping | | 538 | ExternalPort=8080 | | 539 |--------------------->| | 540 | | (2) PCP MAP Request | 541 | |Suggested External Port=8080 | 542 | |---------------------------->| 543 | | | 544 | | (3) PCP MAP Response | 545 | | Assigned External Port=6598 | 546 | |<----------------------------| 547 |(4) AddAnyPortMapping | | 548 | ReservedPort=6598 | | 549 |<---------------------| | 551 Figure 5: Flow example when AddAnyPortMapping() is used 553 5.6.2. AddPortMapping() 555 A dedicated option called PREFER_FAILURE is defined in 556 [I-D.ietf-pcp-base] to toggle the behavior in a PCP Request message. 557 This option is inserted by the IGD-PCP IWF when issuing its requests 558 to the PCP Server only if a specific external port is requested by 559 the IGD Control Point. 561 Upon receipt of AddPortMapping() from an IGD Control Point, the IGD- 562 PCP IWF MUST generate a PCP MAP Request with all requested mapping 563 information as indicated by the IGD Control Point if no NAT is 564 embedded in the IGD or updated as specified in Section 5.5. In 565 addition, the IGD-PCP IWF MUST insert a PREFER_FAILURE Option in the 566 generated PCP request. 568 If the IGD-PCP IWF fails to send the MAP request to its PCP Server, 569 it follows the behavior defined in Section 5.1. 571 If the requested external port is not available, the PCP server will 572 send a CANNOT_PROVIDE_EXTERNAL error response: 574 1. If a short lifetime error is returned, the IGD-PCP IWF MAY resend 575 the same request to the PCP Server after 30 seconds without 576 relaying the error to the IGD Control Point. The IGD-PCP IWF MAY 577 repeat this process until a positive answer is received or some 578 maximum retry limit is reached. When the maximum retry limit is 579 reached, the IGD-PCP IWF relays a negative message to the IGD 580 Control Point with ConflictInMappingEntry as the error code. The 581 maximum retry limit is implementation-specific; its default value 582 is 2. 584 2. If a long lifetime error is returned, the IGD-PCP IWF relays a 585 negative message to the IGD Control Point with 586 ConflictInMappingEntry as the error code. 588 The IGD Control Point may issue a new request with a different 589 requested external port number. This process is typically repeated 590 by the IGD Control Point until a positive answer is received or some 591 maximum retry limit is reached. 593 If the PCP Server is able to create or renew a mapping with the 594 requested external port, it sends a positive response to the IGD-PCP 595 IWF. Upon receipt of the response from the PCP Server, the IGD-PCP 596 IWF stores the returned mapping in its local mapping table, and sends 597 the corresponding positive answer to the requesting IGD Control 598 Point. This answer terminates this exchange. 600 Figure 6 shows an example of the flow exchange that occurs when the 601 PCP Server satisfies the request from the IGD-PCP IWF. Figure 7 602 shows the messages exchange when the requested external port is not 603 available. 605 UPnP-PCP 606 UPnP Control Interworking 607 Point Function PCP Server 608 | | | 609 | (1) AddPortMapping | | 610 | ExternalPort=8080 | | 611 |--------------------->| | 612 | | (2) PCP MAP request | 613 | |Suggested External Port=8080 | 614 | | PREFER_FAILURE | 615 | |---------------------------->| 616 | | | 617 | | (3) PCP MAP response | 618 | | Assigned External Port=8080 | 619 | |<----------------------------| 620 | (4) AddPortMapping | | 621 | ExternalPort=8080 | | 622 |<---------------------| | 624 Figure 6: Flow Example (Positive Answer) 626 UPnP-PCP 627 UPnP Control Interworking 628 Point Function PCP Server 629 | | | 630 | (1) AddPortMapping | | 631 | ExternalPort=8080 | | 632 |--------------------->| | 633 | | (2) PCP MAP Request | 634 | |Suggested External Port=8080 | 635 | | PREFER_FAILURE | 636 | |---------------------------->| 637 | | (3) PCP MAP Response | 638 | | CANNOT_PROVIDE_EXTERNAL | 639 | |<----------------------------| 640 | (4) Error: | | 641 |ConflictInMappingEntry| | 642 |<---------------------| | 643 | (5) AddPortMapping | | 644 | ExternalPort=5485 | | 645 |--------------------->| | 646 | | (6) PCP MAP Request | 647 | |Suggested External Port=5485 | 648 | | PREFER_FAILURE | 649 | |---------------------------->| 650 | | (7) PCP MAP Response | 651 | | CANNOT_PROVIDE_EXTERNAL | 652 | |<----------------------------| 653 | (8) Error: | | 654 |ConflictInMappingEntry| | 655 |<---------------------| | 656 .... 657 | (a) AddPortMapping | | 658 | ExternalPort=6591 | | 659 |--------------------->| | 660 | | (b) PCP MAP Request | 661 | |Suggested External Port=6591 | 662 | | PREFER_FAILURE | 663 | |---------------------------->| 664 | | (c) PCP MAP Response | 665 | | CANNOT_PROVIDE_EXTERNAL | 666 | |<----------------------------| 667 | (d) Error: | | 668 |ConflictInMappingEntry| | 669 |<---------------------| | 671 Figure 7: Flow Example (Negative Answer) 673 Note: According to some experiments, some UPnP 1.0 Control Point 674 implementations, e.g., uTorrent, simply try the same external port 675 a number of times (usually 4 times) and then fail if the port is 676 in use. Also note that some applications use 677 GetSpecificPortMappingEntry() to check whether a mapping exists. 679 5.7. Listing One or a Set of Mappings 681 In order to list active mappings, a IGD Control Point may issue 682 GetGenericPortMappingEntry(), GetSpecificPortMappingEntry(), or 683 GetListOfPortMappings(). 685 GetGenericPortMappingEntry() and GetListOfPortMappings() methods MUST 686 NOT be proxied to the PCP Server since a local mapping is maintained 687 by the IGD-PCP IWF. 689 Upon receipt of GetSpecificPortMappingEntry() from a IGD Control 690 Point, the IGD-PCP IWF MUST check first if the external port number 691 is used by the requesting IGD Control Point. If the external port is 692 already in use by the requesting IGD Control Point, the IGD-PCP IWF 693 MUST send back the mapping entry matching the request. If not, the 694 IGD-PCP IWF MUST relay to the PCP Server a MAP request, with short 695 lifetime (e.g., 60 seconds), including a PREFER_FAILURE Option. If 696 the IGD-PCP IWF fails to send the MAP request to its PCP Server, it 697 follows the behavior defined in Section 5.1. If the requested 698 external port is in use, a PCP error message will be sent by the PCP 699 Server to the IGD-PCP IWF indicating CANNOT_PROVIDE_EXTERNAL as the 700 error cause. Then, the IGD-PCP IWF relays a negative message to the 701 IGD Control Point. If the port is not in use, the mapping will be 702 created by the PCP Server and a positive response will be sent back 703 to the IGD-PCP IWF. Once received by the IGD-PCP IWF, it MUST relay 704 a negative message to the IGD Control Point indicating 705 NoSuchEntryInArray as the error code so that the IGD Control Point 706 knows the queried mapping doesn't exist. 708 5.8. Delete One or a Set of Mappings: DeletePortMapping() or 709 DeletePortMappingRange() 711 A IGD Control Point requests the deletion of one or a list of 712 mappings by issuing DeletePortMapping() or DeletePortMappingRange(). 714 In IGD:2, we assume the IGD applies the appropriate security policies 715 to determine whether a Control Point has the rights to delete one or 716 a set of mappings. When authorization fails, the "606 Action Not 717 Authorized" error code is returned to the requesting Control Point. 719 When DeletePortMapping() or DeletePortMappingRange() is received by 720 the IGD-PCP IWF, it first checks if the requested mappings to be 721 removed are present in the local mapping table. If no mapping 722 matching the request is found in the local table, an error code is 723 sent back to the IGD Control Point: "714 NoSuchEntryInArray" for 724 DeletePortMapping() or "730 PortMappingNotFound" for 725 DeletePortMappingRange(). 727 Figure 8 shows an example of a IGD Control Point asking to delete a 728 mapping which is not instantiated in the local table of the IWF. 730 UPnP-PCP 731 UPnP Control Interworking 732 Point Function PCP Server 733 | | | 734 |(1) DeletePortMapping | | 735 |--------------------->| | 736 | | | 737 | (2) Error: | | 738 | NoSuchEntryInArray | | 739 |<---------------------| | 740 | | | 742 Figure 8: Local Delete (IGD-PCP IWF) 744 If a mapping matches in the local table, a PCP MAP delete request is 745 generated. If no NAT is enabled in the IGD, the IGD-PCP IWF uses the 746 input arguments as included in DeletePortMapping(). If a NAT is 747 enabled in the IGD, the IGD-PCP IWF instead uses the corresponding IP 748 address and port number as assigned by the local NAT. 750 If the IGD-PCP IWF fails to send the MAP request to its PCP Server, 751 it follows the behavior defined in Section 5.1. 753 When a positive answer is received from the PCP Server, the IGD-PCP 754 IWF updates its local mapping table (i.e., removes the corresponding 755 entry) and notifies the IGD Control Point about the result of the 756 removal operation. Once the PCP MAP delete request is received by 757 the PCP Server, it removes the corresponding entry. A PCP MAP 758 SUCCESS response is sent back if the removal of the corresponding 759 entry was successful; if not, a PCP Error is sent back to the IGD-PCP 760 IWF including the corresponding error cause (see Section 4.3). 762 If DeletePortMappingRange() is used, the IGD-PCP IWF does a lookup in 763 its local mapping table to retrieve individual mappings instantiated 764 by the requesting Control Point (i.e., authorization checks) and 765 matching the signaled port range (i.e., the external port is within 766 the "StartPort" and "EndPort" arguments of DeletePortMappingRange()). 767 If no mapping is found, the "730 PortMappingNotFound" error code is 768 sent to the IGD Control Point (Figure 9). If one or more mappings 769 are found, the IGD-PCP IWF generates individual PCP MAP delete 770 requests corresponding to these mappings (see the example shown in 771 Figure 10). 773 The IGD-PCP IWF MAY send a positive answer to the requesting IGD 774 Control Point without waiting to receive all the answers from the PCP 775 Server. 777 UPnP-PCP 778 UPnP Control Interworking 779 Point Function PCP Server 780 | | | 781 |(1)DeletePortMappingRange() | | 782 | StartPort=8596 | | 783 | EndPort =9000 | | 784 | Protocol =UDP | | 785 |--------------------------->| | 786 | | | 787 | (2) Error: | | 788 | PortMappingNotFound | | 789 |<---------------------------| | 790 | | | 792 Figure 9: Flow example when an error encountered when processing 793 DeletePortMappingRange() 795 This example illustrates the exchanges that occur when the IWF 796 receives DeletePortMappingRange(). In this example, only two 797 mappings having the external port number in the 6000-6050 range are 798 maintained in the local table. The IWF issues two MAP requests to 799 delete these mappings. 801 UPnP-PCP 802 UPnP Control Interworking 803 Point Function PCP Server 804 | | | 805 |(1)DeletePortMappingRange() | | 806 | StartPort=6000 | | 807 | EndPort =6050 | | 808 | Protocol =UDP | | 809 |--------------------------->| | 810 | | | 811 | | (2a)PCP MAP Request | 812 | | protocol=UDP | 813 | | internal-ip-address | 814 | | internal-port | 815 | | external-ip-address | 816 | | external-port= 6030 | 817 | | Requested-lifetime= 0 | 818 | |-------------------------->| 819 | | | 820 | | (2c)PCP MAP Request | 821 | | protocol=UDP | 822 | | internal-ip-address | 823 | | internal-port | 824 | | external-ip-address | 825 | | external-port= 6045 | 826 | | Requested-lifetime= 0 | 827 | |-------------------------->| 828 | | | 829 | (2b)Positive answer | | 830 |<---------------------------| | 831 | | | 833 Figure 10: Example of DeletePortMappingRange() 835 5.9. Renewing a Mapping 837 Because of the incompatibility of mapping lifetimes between UPnP IGD 838 and PCP, the IGD-PCP IWF MUST simulate long and even infinite 839 lifetimes. Indeed, for requests having a requested infinite 840 PortMappingLeaseDuration, the IGD-PCP IWF MUST set the Requested 841 Lifetime of the corresponding PCP request to 4294967296. If 842 PortMappingLeaseDuration is not infinite, the IGD-PCP IWF MUST set 843 the Requested Lifetime of the corresponding PCP request to the same 844 value as PortMappingLeaseDuration. Furthermore, the IGD-PCP 845 Interworking Function MUST maintain an additional timer set to the 846 initial requested PortMappingLeaseDuration. Upon receipt of a 847 positive answer from the PCP server, the IGD-PCP IWF relays the 848 corresponding UPnP IGD response to the requesting IGD Control Point 849 with PortMappingLeaseDuration set to the same value as the one of the 850 initial request. Then, the IGD-PCP IWF MUST periodically renew the 851 constructed PCP mapping until the expiry of PortMappingLeaseDuration. 852 Responses received when renewing the mapping MUST NOT be relayed to 853 the IGD Control Point. 855 In case an error is encountered during mapping renewal, the IGD-PCP 856 Interworking Function has no means to inform the IGD Control Point. 858 5.10. Rapid Recovery 860 When the IGD-PCP IWF is co-located with the DHCP server, the state 861 maintained by the IGD-PCP IWF MUST be updated using the state in the 862 local DHCP server. Particularly, if an IP address expires or is 863 released by an internal host, the IGD-PCP IWF MUST delete all the 864 mappings bound to that internal IP address. 866 Upon change of the external IP address of the IGD-PCP IWF, the IGD- 867 PCP IWF MAY renew the mappings it maintained. This can be achieved 868 only if a full state table is maintained by the IGD-PCP IWF. If the 869 port quota is not exceeded in the PCP server, the IGD-PCP IWF will 870 receive a new external IP address and port numbers. The IGD-PCP IWF 871 has no means to notify the change of the external IP address and port 872 to internal IGD Control Points. Stale mappings will be maintained by 873 the PCP Server until their lifetime expires. 875 Note: If an address change occurs, protocols that are sensitive to 876 address changes will experience disruption (e.g., TCP). 878 [I-D.ietf-pcp-base] defines a procedure for the PCP Server to notify 879 PCP Clients about changes related to the mappings it maintains. When 880 an unsolicited ANNOUNCE is received, the IGD-PCP IWF makes one or 881 more MAP requests with the PREFER_FAILURE option to re-install its 882 mappings. If the PCP server cannot create the requested mappings 883 (signaled with the CANNOT_PROVIDE_EXTERNAL error response), the IGD- 884 PCP IWF has no means to notify the change of the external IP address 885 and port to internal IGD Control Points. 887 Unsolicited PCP MAP responses received from a PCP Server are handled 888 as any normal MAP response. If a response indicates that the 889 external IP address or port has changed, the IGD-PCP IWF has no means 890 to notify the internal IGD Control Point of this change. 892 Further analysis of PCP failure scenarios for the IGD-PCP 893 Interworking Function are discussed in [I-D.boucadair-pcp-failure]. 895 6. IANA Considerations 896 This document makes no request of IANA. 898 Note to RFC Editor: this section may be removed on publication as an 899 RFC. 901 7. Security Considerations 903 IGD:2 access control requirements and authorization levels SHOULD be 904 applied by default [IGD2]. When IGD:2 is used, operation on the 905 behalf of a third party SHOULD be allowed only if authentication and 906 authorization are used [IGD2]. When only IGD:1 is available, 907 operation on the behalf of a third party SHOULD NOT be allowed. 909 This document defines a procedure to create PCP mappings for third 910 party devices belonging to the same subscriber. Means to prevent a 911 malicious user from creating mappings on behalf of a third party must 912 be enabled as discussed in Section 13.1 of [I-D.ietf-pcp-base]. In 913 particular, THIRD_PARTY option MUST NOT be enabled unless the network 914 on which the PCP messages are to be sent is fully trusted. For 915 example if access control lists are installed on the PCP client, PCP 916 server, and the network between them, so those ACLs allow only 917 communications from a trusted PCP client to the PCP server. 919 An IGD Control Point which issues AddPortMapping(), 920 AddAnyPortMapping(), or GetSpecificPortMappingEntry() requests in a 921 shorter time frame will create a lot of mapping entries on the PCP 922 server. Means to avoid exhausting port resources (e.g., port quota 923 discussed in Section 17.2 of [I-D.ietf-pcp-base]) SHOULD be enabled. 925 The security considerations discussed in [I-D.ietf-pcp-base] and 926 [Sec_DCP] should be taken into account. 928 8. Acknowledgments 930 Authors would like to thank F. Fontaine, C. Jacquenet, X. Deng, G. 931 Montenegro, D. Thaler, R. Tirumaleswar, P. Selkirk, T. Lemon, V. 932 Gurbani, and P. Yee for their review and comments. 934 F. Dupont contributed to previous versions of this document. Thanks 935 to him for his thorough reviews and contribution. 937 9. References 938 9.1. Normative References 940 [I-D.ietf-pcp-base] 941 Wing, D., Cheshire, S., Boucadair, M., Penno, R., and P. 942 Selkirk, "Port Control Protocol (PCP)", draft-ietf-pcp- 943 base-29 (work in progress), November 2012. 945 [IGD1] UPnP Forum, , "WANIPConnection:1 Service (http:// 946 www.upnp.org/specs/gw/UPnP-gw- 947 WANIPConnection-v1-Service.pdf)", November 2001. 949 [IGD2] UPnP Forum, , "WANIPConnection:2 Service (http://upnp.org/ 950 specs/gw/UPnP-gw-WANIPConnection-v2-Service.pdf)", 951 September 2010. 953 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 954 Requirement Levels", BCP 14, RFC 2119, March 1997. 956 9.2. Informative References 958 [I-D.boucadair-pcp-failure] 959 Boucadair, M. and R. Penno, "Port Control Protocol (PCP) 960 Failure Scenarios", draft-boucadair-pcp-failure-05 (work 961 in progress), February 2013. 963 [I-D.ietf-pcp-description-option] 964 Boucadair, M., Penno, R., and D. Wing, "PCP Description 965 Option", draft-ietf-pcp-description-option-00 (work in 966 progress), March 2013. 968 [I-D.ietf-pcp-dhcp] 969 Boucadair, M., Penno, R., and D. Wing, "DHCP Options for 970 the Port Control Protocol (PCP)", draft-ietf-pcp-dhcp-07 971 (work in progress), March 2013. 973 [I-D.ietf-pcp-proxy] 974 Boucadair, M., Penno, R., and D. Wing, "Port Control 975 Protocol (PCP) Proxy Function", draft-ietf-pcp-proxy-02 976 (work in progress), February 2013. 978 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 979 NAT64: Network Address and Protocol Translation from IPv6 980 Clients to IPv4 Servers", RFC 6146, April 2011. 982 [RFC6333] Durand, A., Droms, R., Woodyatt, J., and Y. Lee, "Dual- 983 Stack Lite Broadband Deployments Following IPv4 984 Exhaustion", RFC 6333, August 2011. 986 [Sec_DCP] UPnP Forum, , "Device Protection:1", February 2011, 987 <(http://upnp.org/specs/gw/UPnP-gw- 988 DeviceProtection-v1-Service.pdf>. 990 Authors' Addresses 992 Mohamed Boucadair 993 France Telecom 994 Rennes 35000 995 France 997 Email: mohamed.boucadair@orange.com 999 Reinaldo Penno 1000 Cisco Systems, Inc. 1001 170 West Tasman Drive 1002 San Jose, California 95134 1003 USA 1005 Email: repenno@cisco.com 1007 Dan Wing 1008 Cisco Systems, Inc. 1009 170 West Tasman Drive 1010 San Jose, California 95134 1011 USA 1013 Email: dwing@cisco.com