idnits 2.17.1 draft-ietf-mif-api-extension-05.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 : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == There are 5 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet has text resembling RFC 2119 boilerplate text. -- The document date (February 15, 2014) is 3722 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.scharf-mptcp-api' is defined on line 723, but no explicit reference was found in the text == Unused Reference: 'RFC3493' is defined on line 728, but no explicit reference was found in the text == Outdated reference: A later version (-11) exists of draft-ietf-mif-mpvd-arch-00 == Outdated reference: A later version (-04) exists of draft-scharf-mptcp-api-02 Summary: 0 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 MIF D. Liu 2 Internet-Draft China Mobile 3 Intended status: Informational Ted. Lemon 4 Expires: August 19, 2014 Nominum 5 Yuri. Ismailov 6 Ericsson 7 Z. Cao 8 China Mobile 9 February 15, 2014 11 MIF API consideration 12 draft-ietf-mif-api-extension-05 14 Abstract 16 Hosts may connect to the internet using more than one network API at 17 a time, or to a single network on which service is provided by more 18 than one provider. Existing APIs are inadequate to allow 19 applications to successfully use the network in this environment. 20 This document presents a new abstract API that provides the minimal 21 set of messages required to enable an application to communicate 22 successfully in this environment. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on August 19, 2014. 41 Copyright Notice 43 Copyright (c) 2014 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Conventions used in this document . . . . . . . . . . . . . . 3 60 3. MIF API Concept . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1. Provisioning Domains . . . . . . . . . . . . . . . . . . 4 62 3.2. MIF API Elements . . . . . . . . . . . . . . . . . . . . 4 63 3.2.1. Application Element . . . . . . . . . . . . . . . . . 5 64 3.2.2. High Level API . . . . . . . . . . . . . . . . . . . 5 65 3.2.3. MIF API . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.2.4. Communications API . . . . . . . . . . . . . . . . . 6 67 3.2.5. Network Link API . . . . . . . . . . . . . . . . . . 6 68 3.2.6. MIF API communication model . . . . . . . . . . . . . 7 69 3.2.7. MIF Messages . . . . . . . . . . . . . . . . . . . . 7 70 3.3. Example Usage . . . . . . . . . . . . . . . . . . . . . . 14 71 4. Security Considerations . . . . . . . . . . . . . . . . . . . 16 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 73 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 74 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 7.1. Normative References . . . . . . . . . . . . . . . . . . 16 76 7.2. Informative References . . . . . . . . . . . . . . . . . 16 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 79 1. Introduction 81 Traditionally, applications that communicate on the network have done 82 so over a single network link, which is provided by a single service 83 provider. However, this operating environment is now the exception 84 rather than the rule. Most devices now have multiple wireless 85 interfaces that are, in practice, connected to networks operated by 86 different providers. These networks may or may not have different 87 reachability characteristics with respect to any given service an 88 application may wish to connect to. 90 For example, consider a typical modern host with two wireless 91 interfaces: a wireless interface connected to a broadband network, 92 and another connected to some kind of cellular network. The same 93 host may also have a wired interface which is sometimes connected to 94 a third broadband link. It is also quite common for hosts to have 95 VPN links that are configured, for example, for access to corporate 96 networks, or for access to network privacy services. 98 As a result, it is now quite typical that a program attempting to 99 communicate in such an environment will be presented with conflicting 100 configuration information from more than one provider. In addition, 101 the cost of bandwidth on different links and the power required ny 102 those links may require consideration. 104 The API specified in this document is intended to describe the 105 minimal complete set of API calls required to implement higher level 106 APIs that solve these problems. It is not expected that applications 107 will be implemented to this API, although it should be possible to do 108 so. Rather, we expect this API to be used as a basis for building 109 higher-level APIs that provide domain-specific solutions to these 110 problems. The reason for specifying a lower-level API is to enable 111 any arbitrary domain- specific API to be implemented, since no single 112 higher-level API is likely to satisfy the needs of every application. 114 The API specified here is an abstract API. This means that we 115 specify the functionality that is required to implement the API, but 116 we do not provide specific bindings for any programming language: 117 these are left up to the implementation. The API is described in 118 terms of messages sent and messages received, rather than in terms of 119 procedure calls, because it is necessary to be able to interleave 120 these messages; a procedure call API necessarily precludes 121 interleaving. 123 This document is intended to be read and used as a checklist by 124 operating system vendors who are interested in providing adequate 125 functionality to applications that must run on hosts in environments 126 like the ones described here. It should also be useful to purchasers 127 of devices that must operate in such environments, so that they can 128 tell if they are getting a device that can actually succeed in these 129 environments. 131 2. Conventions used in this document 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL","SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in RFC 2119 [RFC2119]. 137 3. MIF API Concept 139 The MIF API is intended to deal with situations where more than one 140 interface may be active at a time. It must also deal with situations 141 where a single interface is connected to a link that provides more 142 than one type of network service. The most common example of this 143 that we expect is a dual-stack network configuration. 145 3.1. Provisioning Domains 147 Document [I-D.ietf-mif-mpvd-arch] defines Provisioning Domain (PvD) 148 architecture and its associated mechanism, such as PvD identity/ 149 naming concept, conveying mechanism etc. According to 150 [I-D.ietf-mif-mpvd-arch], a provisioning domain is a consistent set 151 of network configuration information. Classically, the entire set 152 available on a single interface is provided by a single source, such 153 as network administrator, and can therefore be treated as a single 154 provisioning domain. In modern IPv6 networks, multihoming can result 155 in more than one provisioning domain being present on a single link. 157 To properly handle these multiple-service interfaces, we specify the 158 API not in terms of interfaces, but in terms of provisioning domains. 159 From the perspective of the MIF API, a provisioning domain consists 160 of a link, plus all the configuration information received on that 161 link for that provisioning domain. So for an IPv4 provisioning 162 domain, that would be whatever information is received from the DHCP 163 server. For an IPv6 provisioning domain, the information received 164 through router advertisements would be combined with the information 165 recieved via DHCPv6. 167 3.2. MIF API Elements 169 There are a number of different, essentially independent, pieces of 170 software that need to be connected together in order to fully support 171 a successful MIF communication strategy. These elements are shown in 172 figure 3.1. 174 +-------------------------------------------+ 175 | Application | 176 +-------------------------------------------+ 177 /\ || /\ || /\ || 178 || \/ || || || || 179 +--------------------+ || || || || 180 | High Level API | || || || || 181 +--------------------+ || || || || 182 /\ || || || || || 183 || \/ || \/ || || 184 +------------------------------+ || || 185 | MIF API | || || 186 +------------------------------+ || || 187 /\ || || \/ 188 || || +-------------------------------+ 189 || || + Communications API + 190 || || +-------------------------------+ 191 || || /\ || 192 || \/ || \/ 193 +-------------------------------------------+ 194 | Network Link API | 195 +-------------------------------------------+ 196 /\ || /\ || 197 || \/ || \/ 198 +-------------------+ +--------------------+ 199 | Network Interface | | Network Interface | 200 | 1 | | 2 | 201 +-------------------+ +--------------------+ 203 Figure 1: MIF API Elements 205 3.2.1. Application Element 207 This is an actual application. Applications fall into a variety of 208 broad categories, including network servers, web browsers, peer-to- 209 peer programs, and so on. Although we are focusing here on the 210 mechanisms required to allow these applications to originate 211 connections to remote nodes, it is worth noting that applications 212 must also be able to receive connections from remote nodes. 214 3.2.2. High Level API 216 Applications are generally expected to originate connections using 217 some general-purpose high-level API suited to their particular 218 function. It is likely that different applications may use different 219 high-level APIs to communicate, depending on their particular needs. 220 We do not describe the functioning of such high-level APIs; however, 221 one such API under current consideration is the Happy Eyeballs for 222 MIF [reference]. These APIs are expected to be able to be 223 implemented using functionality like that described in the MIF API. 225 3.2.3. MIF API 227 This is the API being described in this document. Generally 228 speaking, this API is used by higher-level APIs. However, it is 229 permissible for applications to use the MIF API when it is deemed 230 necessary. Currently, several modern web browsers take this approach 231 to establishing network connections, rather than relying on vendor- 232 provided connection mechanisms. 234 3.2.4. Communications API 236 Once an application has originated a connection with a remote node 237 using either a high-level API or the MIF API, it must communicate. 238 Similarly, when an application receives a connection from a remote 239 node, it must communicate with that remote node. The communications 240 API is used for this communication. Popular examples of such APIs 241 include the POSIX socket API and a variety of other related APIs. 243 It is likely that in some instances, implementations of the MIF API 244 will be done as extensions to the Communications API provided by a 245 particular operating system; the functional separation we show here 246 is intended to allow us to illustrate only those features required in 247 a MIF environment, while relying on existing communications APIs to 248 provide the rest. 250 3.2.5. Network Link API 252 This is the software that is responsible for actually managing 253 whatever network links are present on a node, whether these are 254 physical links or tunnels. What precisely this functional box 255 contains may vary greatly from device to device. On a typical modern 256 computer workstation, this functionality would almost certainly 257 reside entirely in the system kernel; however, on an embedded device 258 everything from the Application down to the Network Link API could 259 easily be running together on the bare metal as a single program. 261 The Network Link API can completely concealed from the Application, 262 so we don't show a connection between them on the functional diagram, 263 and indeed we do not talk about the functionality provided by this 264 API. The reason for showing it on the functional diagram is simply 265 to show that there likely is an API in common between MIF and the 266 Communications API. 268 3.2.6. MIF API communication model 270 MIF API requests are made in the form of messages posted to the MIF 271 API, and messages received from it. To accomplish this, several API 272 calls are available. These calls mediate communication between the 273 MIF API and the High Level API, or between the MIF API and the 274 Application. In addition, the CHECK MESSAGE call allows the 275 application to probe for or wait for messages from any of the APIs. 277 3.2.6.1. POST MESSAGE call 279 This call causes a message to be posted to the MIF API. The call 280 posts the message, and then returns. 282 3.2.6.2. CHECK MESSAGE call 284 This call checks to see if there is a message waiting either from the 285 High Level API, the MIF API, or the Communications API. Ideally it 286 should be able to report the availability of any message or event 287 that the application might anticipate receiving, so that the 288 application can simply block waiting for such an event using this 289 call. The application should be able to do a non-blocking probe, 290 wait for some limited period of time, or wait indefinitely. 292 An example of a function of this type in existing practice is the 293 POSIX poll() system call. 295 3.2.6.3. GET MESSAGE call 297 This call checks to see if there is a message waiting. If there is 298 no message, it returns a status code indicating that there is no 299 message waiting. If there is a message, it returns the message. 301 3.2.7. MIF Messages 303 MIF messages always go in one direction or the other: from the 304 subscriber to the MIF API, or to the subscriber from the MIF API. We 305 use the term "subscriber" here to mean either the Application or the 306 High Level API, since either is permitted to communicate with the MIF 307 API. 309 Messages described here are grouped according to function. 311 3.2.7.1. Announce Interfaces 313 This message is sent to the MIF API to ask it to send a message 314 announcing the existence of any interface. When the MIF API receives 315 this message from a subscriber, it iterates across the list of all 316 known interfaces; for each known interface, it sends an Interface 317 Announcement message to the subscriber. 319 In addition, the MIF API sets a flag indicating that the subscriber 320 is interested in learning about new interfaces. When the MIF API 321 detects the presence of a new interface, it sends an Interface 322 Announcement message for that interface to the subscriber. This 323 would happen, for instance, when a new tunnel is configured, or when 324 a USB device that is a network interface is discovered by the Network 325 API. 327 Also, if a network interface goes away, either because the physical 328 network device is disconnected, or because a tunnel is disabled, the 329 MIF API will send a No Interface Announcement message to the 330 subscriber. 332 3.2.7.2. Stop Announcing Interfaces 334 This message is sent to the MIF API when a subscriber is no longer 335 interested in receiving announcements about new interfaces. 336 Subsequently, the MIF API will no longer send Interface Announcement 337 or No Interface Announcement messages to the subscriber. 339 3.2.7.3. Interface Announcement 341 This message announces the existence of an interface. The 342 announcement includes an interface display name and interface 343 identifier. 345 3.2.7.4. No Interface Announcement 347 This message announces that an interface that had been previously 348 announced is no longer present. The announcement includes the 349 interface identifier. 351 3.2.7.5. Announce Provisioning Domain 353 This message requests the MIF API to announce the availability of any 354 provisioning domains configured on a particular interface. The 355 interface identifier must be specified. 357 Upon receipt, the MIF API will iterate across the list of 358 Provisioning Domains present for a particular interface, and will 359 send a Provisioning Domain Announcement for each such Provisioning 360 Domain. 362 In addition, the MIF API will set a flag indicating that the 363 subscriber wishes to know about new provisioning domains as they 364 appear. Subsequently, when a new Provisioning Domain appears, the 365 MIF API will send a Provisioning Domain Announcement message to the 366 subscriber. 368 Finally, if a Provisioning Domain expires or is invalidated, the MIF 369 API will send the subscriber a No Provisioning Domain Announcement 370 message for that Provisioning Domain. 372 In the event that an interface on which provisioning domains has been 373 announced goes away, a No Provisioning Domain Announcement message 374 will be sent for each provisioning domain that had previously been 375 announced on that interface before the No Interface Announcement 376 message is sent. 378 Once a No Interface Announcement message has been sent, any 379 subscriber that had subscribed to Provisioning Domain announcements 380 for that interface will be automatically unsubscribed. 382 3.2.7.6. Stop Announcing Provisioning Domains 384 This message requests that the MIF API stop sending the subscriber 385 Provisioning Domain Announcement and No Provisioning Domain 386 Announcement messages. The subscriber must indicate the interface 387 for which it no longer wishes to receive Provisioning Domain 388 announcements. 390 3.2.7.7. Provisioning Domain Announcement 392 This message is sent by the MIF API to the subscriber to indicate 393 that a new Provisioning Domain has successfully been configured on an 394 interface. The announcement includes the interface identifier and 395 the provisioning domain identifier. 397 3.2.7.8. No Provisioning Domain Announcement 399 This message is sent by the MIF API to the subscriber to indicate 400 that an existing, previously announced provisioning domain has 401 expired or otherwise become invalid, and can no longer be used. 403 3.2.7.9. Announce Configuration Element 405 This message is sent by the subscriber to request a specific 406 configuration element from a specific provisioning domain. A 407 provisioning domain identifier must be specified. 409 The MIF API will respond by iterating across the complete list of 410 configuration elements for a provisioning domain, sending a 411 Configuration Element Announcement message to the subscriber for each 412 one. 414 Additionally, if any Configuration Elements subsequently complete for 415 a particular provisioning domain, the MIF API will send a 416 Configuration Element Announcement message to the subscriber for each 417 such element. If a Configuration Element becomes invalidated after 418 it has been announced, the MIF API will send a No Configuration 419 Element message. 421 If a provisioning domain expires or becomes invalid, the MIF API will 422 iterate across the list of remaining configuration elements for that 423 provisioning domain amd send a No Configuration Element Announcement 424 message for each such configuration element. 426 3.2.7.10. Configuration Element Announcement 428 The Configuration Element Announcement message includes a 429 Provisioning Domain ID and a Configuration Element Type, which can be 430 one of the following: Config Element RA Config Element DHCPv6 Config 431 Element DHCPv4 etc. 433 3.2.7.11. No Configuration Element Announcement 435 The No Configuration Element Announcement message indicates that a 436 previously valid configuration element for a provisioning domain is 437 no longer valid. The message includes a provisioning domain 438 identifier and a configuration element type. 440 3.2.7.12. Stop Announce Configuration Element 442 The Stop Announce Configuration Element message requests that MIF API 443 stop announce configuration element. 445 3.2.7.13. Announce Address 447 This message is sent by the subscriber to request announcements of 448 valid IP addresses for a specific provisioning domain. A 449 provisioning domain identifier must be specified. 451 The MIF API will respond by iterating across the complete list of 452 configuration elements for a provisioning domain, sending a Address 453 Announcement message to the subscriber. 455 Additionally, if any new Address is subsequently configured on a 456 particular provisioning domain, the MIF API will send an Address 457 Announcement message to the subscriber for each such element. If an 458 address becomes invalidated after it has been announced, the MIF API 459 will send a No Address Announcement message. 461 If a provisioning domain expires or becomes invalid, the MIF API will 462 iterate across the list of remaining configuration elements for that 463 provisioning domain amd send a No Address Announcement message for 464 each such address. 466 3.2.7.14. Address Announcement 468 The Address Announcement message includes single IPv4 or IPV6 address 469 and a Provisioning Domain identifier, as well as the valid and 470 preferred lifetimes for that IP address (IPv6 only). 472 3.2.7.15. Stop Announcing Address 474 The Stop Announcing Address message requests the MIF API to stop 475 announcing address. 477 3.2.7.16. No Address Announcement 479 The No Address Announcement message indicates that a previously valid 480 address for a provisioning domain is no longer valid. The message 481 includes a provisioning domain identifier and an IPv4 or IPv6 482 address. 484 3.2.7.17. Get Configuration Data 486 The Get Configuration Data message is sent to the MIF API, and 487 includes a Provisioning Domain ID, a Configuration Element Type, and 488 a Configuration Information Identifier. 490 Configuration Information Identifiers: DNS Server List etc. 492 The MIF API searches the configuration database for the specific type 493 of Configuration Element on the specified Provisioning Domain to see 494 if there is any configuration data of the specified type. If so, the 495 MIF API sends a Configuration Data message to the subscriber; 496 otherwise it sends a No Configuration Data message to the subscriber. 498 3.2.7.18. Translate Name 500 The Translate Name message is sent to the MIF API. It includes a 501 provisioning domain and a name, which is a UTF8 string naming a 502 network node. The message also includes a Translation Identifier, 503 which the subscriber must ensure is unique across all outstanding 504 name service requests. 506 The MIF API begins a name resolution process. As results come in 507 from the name resolution process, the MIF API sends Name Translation 508 messages to the subscriber for each such result. 510 Name resolution can be handled by one or more translations systems 511 such as local host table lookup, Domain Name System, NIS, LLMNR, and 512 is implementation-dependent. **need to think about this 514 3.2.7.19. Stop Translating Name 516 This message is sent to the MIF API to indicate that the subscriber 517 is no longer interested in additional results from a particular name 518 translation process. The message includes the Translation 519 Identifier. 521 3.2.7.20. Name Translation 523 The MIF API sends a Name Translation message to subscribers whenever 524 results come in from a name translation process being performed on 525 behalf of the subscriber. The Name Translation message includes the 526 Translation ID generated by the subscriber, and an IP address 527 returned by the translation process. If a single translation result 528 contains more than one IP address, or IP addresses of different 529 types, the MIF API sends a single Name Translation message for each 530 such IP address. 532 3.2.7.21. Connect to PvD 534 The Connect to PvD message is used for the advanced application to 535 select the PvD. Advanced application can use this message to select 536 a specific PvD by providing the PvD identifier as parameter. This is 537 the advanced case that discussed in section 6.3 of 538 [I-D.ietf-mif-mpvd-arch]. 540 3.2.7.22. Connect to Address 542 The Connect to Address message contains an IP address, a provisioning 543 domain identifier, and a connection identifier which the subscriber 544 must ensure is unique. The MIF API attempts to initiate a TCP 545 connection to the specified IP address using one or more source 546 addresses that are valid for the specified provisioning domain, 547 according to the source address selection policy for that 548 provisioning domain. 550 If the connection subsequently succeeds, the MIF API will send a 551 Connected message to the subscriber. If it subsequently fails, the 552 MIF API will send a Not Connected message to the subscriber. 554 3.2.7.23. Connect to Address From Address 556 The Connect to Address From Address message contains a source IP 557 address, a destination IP address, a provisioning domain identifier, 558 and a connection identifier which the subscriber must ensure is 559 unique. The MIF API attempts to initiate a TCP connection to the 560 specified IP address using the specified source address. 562 If the connection subsequently succeeds, the MIF API will send a 563 Connected message to the subscriber. If it subsequently fails, the 564 MIF API will send a Connection Failed message to the subscriber. 566 3.2.7.24. Connected 568 The Connected message contains the connection identifier that was 569 provided in a previous Connect to Address or Connect to Address From 570 Address message sent by the subscriber. It also contains an token, 571 suitable for use with the connection API, for communicating with the 572 end node to which the connection was established. 574 3.2.7.25. Not Connected 576 The Not Connected message contains the connection identifier that was 577 provided in a previous Connect to Address or Connect to Address From 578 Address message sent by the subscriber. It also contains an 579 indication as to what went wrong with the connection. 581 3.2.7.26. Application Connectivity Management 583 The following APIs are used for application connectivity management. 585 3.2.7.26.1. Application: Wants to connect 587 This message is sent by the application to the MIF API that indicates 588 the application wants to connect to the network. The purpose of this 589 call is to trigger the MIF API to engage in any work that is required 590 to configure the network. If all interfaces are already operational, 591 this message is a no-op. An application would typically send this 592 message either because it has no provisioning domains on which it can 593 attempt to connect, or because it has failed to connect on any 594 existing provisioning domain. 596 3.2.7.26.2. Application: Connection is idle 598 This message is sent by the applicaiton to the MIF API to indicate 599 that the application is not expecting to receive any data or send any 600 data. This is a signal to the MIF API that, for example a radio that 601 consumes a lot of power can be put into a temporary idle state, but 602 that the application expects to resume communication in the future 603 using the existing connection. 605 3.2.7.26.3. Application: Connection can be broken 607 This message is sent by the application to the MIF API to indicate 608 that the application can tolerate the connection being broken. This 609 is a signal that the application could use the connection in the 610 future if it were not broken, but can re-establish the connection if 611 it is broken without any loss of functionality. A MIF API 612 implementation on a power-conservative device might take this as a 613 signal to shut down radios to conserve power. 615 3.2.7.26.4. Interface is going away 617 This message is sent by the MIF API to the application to indicate 618 that an interface is going away. This can happen when the interface 619 is still up but the system intends to take it down. 621 3.2.7.26.5. Interface is going up 623 This message is sent by the MIF API to the application to indicate 624 that an interface is going up. This can happen when the interface is 625 still down but the system intends to take it up. 627 3.3. Example Usage 628 +-------+ +-------+ 629 | APP | | API | 630 +-------+ +-------+ 631 | Announce Interfaces | 632 |-------------------------------------------->| 633 | Interface 1, eth0 | 634 |<--------------------------------------------| 635 | Announce PDs on Interface 1 | 636 |-------------------------------------------->| 637 | PD 1 | 638 |<--------------------------------------------| 639 | Interface 2, wa0 | 640 |<--------------------------------------------| 641 | PD 2 | 642 |<--------------------------------------------| 643 | Announce PDs on Interface 2 | 644 |-------------------------------------------->| 645 | PD 3 | 646 |DNS query 2001::1, host.example.com A,AAAA | 647 |DNS query 192.168.1.1,host.example.com A,AAAA| 648 |DNS query 2001::1, host.example.com A,AAAA | 649 |-------------------------------------------->| 650 |14. 2001::1 DNS response: | 651 | host.example.com | 652 | IN A 14.15.16.17 | 653 | IN AAAA 2001:192:321::1 | 654 | | 655 | 2002::1 DNS response:... | 656 | 192.168.1.1 DNS response: | 657 | IN A 192.168.1.1 | 658 |<--------------------------------------------| 659 | 15. SYN: 14.15.16.17 @ IF1 | 660 | SYN: 2001:192:321::1 @ IF1 | 661 | SYN: 2001:192:321::1 @ IF2 | 662 | SYN: 192.168.1.1 @ IF1 | 663 |-------------------------------------------->| 664 | 16. SYN+ACK @ 192.168.1.1 IF1 | 665 | SYN+ACK @ 2001:192:321::1 IF2 | 666 | SYN+ACK @ 2001:192:321::1 IF1 | 667 |<--------------------------------------------| 668 | | 670 MIF API communication model 672 As shown in the preceding example, the application first invokes the 673 MIF API to get a list of all the network interfaces in the host. As 674 soon as each interface has been identified, the application invokes 675 the MIF API to get a list of provisioning domains that are attached 676 to that interface. 678 The application then invokes the MIF API to look up a name in the 679 context of each provisioning domain. The name lookup may return more 680 than one IP address for each queried host name. 682 The The application then tries to connect to each such IP addresses 683 by sending tcp SYN packet to each destination IP addresses through 684 the provisioning domain on which it received that name. Some of the 685 destination IP addresses may return an ACK packet; others may not. 687 The application then chooses a connection based on its preferred 688 criteria. For example, the criteria may based on the quality of the 689 link, who answered first, or whether, for example, a TLS 690 authentication succeeds on that connection. 692 4. Security Considerations 694 This document specifies an abstract API and will not affect any 695 existing protocols. It does not introduce any new security risk. 697 5. IANA Considerations 699 None 701 6. Acknowledgments 703 The authors want to thank Teemu Savolainen from Nokia, Dayi Zhao from 704 Bitway, Dave Thaler from Microsoft and others for their useful 705 suggestions and discussions. We would also like to acknowledge Yuri 706 Ismailov's work as the author of the initial version of this 707 document, but was drawn away by other work and let us continue. 709 7. References 711 7.1. Normative References 713 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 714 Requirement Levels", BCP 14, RFC 2119, March 1997. 716 7.2. Informative References 718 [I-D.ietf-mif-mpvd-arch] 719 Anipko, D., "Multiple Provisioning Domain Architecture", 720 draft-ietf-mif-mpvd-arch-00 (work in progress), February 721 2014. 723 [I-D.scharf-mptcp-api] 724 Scharf, M. and A. Ford, "MPTCP Application Interface 725 Considerations", draft-scharf-mptcp-api-02 (work in 726 progress), July 2010. 728 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 729 Stevens, "Basic Socket Interface Extensions for IPv6", RFC 730 3493, February 2003. 732 Authors' Addresses 734 Dapeng Liu 735 China Mobile 736 Unit2, 28 Xuanwumenxi Ave,Xuanwu District 737 Beijing 100053 738 China 740 Email: liudapeng@chinamobile.com 742 Ted Lemon 743 Nominum 744 Redwood City 745 CA 94063 746 USA 748 Email: Ted.Lemon@nominum.com 750 Yuri Ismailov 751 Ericsson 752 Stockholm 753 Sweden 754 USA 756 Email: yuri@ismailov.eu 758 Zhen Cao 759 China Mobile 760 Unit2, 28 Xuanwumenxi Ave,Xuanwu District 761 Beijing 100053 762 China 764 Email: caozhen@chinamobile.com