idnits 2.17.00 (12 Aug 2021) /tmp/idnits42256/draft-schilcher-mobike-trigger-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 17. -- Found old boilerplate from RFC 3978, Section 5.5 on line 522. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 499. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 506. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 512. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 148: '...nect, etc. are not supported and MUST...' RFC 2119 keyword, line 159: '...onal information MAY be included (e.g....' RFC 2119 keyword, line 295: '...ered application MUST NOT respond to i...' RFC 2119 keyword, line 398: '...all other fields SHOULD be set to zero...' RFC 2119 keyword, line 426: '... value MUST be set to zero....' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year ** The document contains RFC2119-like boilerplate, but doesn't seem to mention RFC 2119. The boilerplate contains a reference [2], but that reference does not seem to mention RFC 2119 either. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 14, 2005) is 6304 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 2367 (ref. '1') -- Possible downref: Non-RFC (?) normative reference: ref. '2' == Outdated reference: draft-ietf-mobike-design has been published as RFC 4621 Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IKEv2 Mobility and Multihoming U. Schilcher 3 (mobike) H. Tschofenig 4 Internet-Draft Siemens 5 Expires: August 18, 2005 February 14, 2005 7 Application Programming Interface to a Trigger Database for MOBIKE 8 draft-schilcher-mobike-trigger-api-00.txt 10 Status of this Memo 12 This document is an Internet-Draft and is subject to all provisions 13 of Section 3 of RFC 3667. By submitting this Internet-Draft, each 14 author represents that any applicable patent or other IPR claims of 15 which he or she is aware have been or will be disclosed, and any of 16 which he or she become aware will be disclosed, in accordance with 17 RFC 3668. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as 22 Internet-Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on August 18, 2005. 37 Copyright Notice 39 Copyright (C) The Internet Society (2005). 41 Abstract 43 One of the functionality of MOBIKE is to create and to maintain a set 44 of available addresses and to provide them to the communication 45 partner. A MOBIKE peer should have some information about the status 46 of each address in order to execute the respective actions (e.g., 47 switching from one preferred address to another). This information, 48 which will be referred as trigger, is distributed over a number of 49 protocols daemons at an end host. To make this information available 50 to the MOBIKE daemon it is necessary to store it centrally at the 51 host (called trigger database) and to enable the protocols to insert 52 the triggers and to allow MOBIKE to obtain timely information. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Trigger Classification . . . . . . . . . . . . . . . . . . . 5 59 4. API for the Trigger Database . . . . . . . . . . . . . . . . 6 60 5. Supported Message Types . . . . . . . . . . . . . . . . . . 7 61 6. Payload Format . . . . . . . . . . . . . . . . . . . . . . . 10 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 13 63 8. Security Considerations . . . . . . . . . . . . . . . . . . 14 64 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 15 65 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 66 10.1 Normative References . . . . . . . . . . . . . . . . . . 16 67 10.2 Informative References . . . . . . . . . . . . . . . . . 16 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 16 69 Intellectual Property and Copyright Statements . . . . . . . 17 71 1. Introduction 73 When a MOBIKE implementation is started first it has to build a set 74 of all available addresses (or a subset of them for policy reasons; 75 see [3]) before communicating with another peer. From these 76 addresses, it has to select one of the addresses as preferred address 77 that will be used as the source address in the communication with the 78 MOBIKE peer. 80 This address set together with the preferred address may change 81 during operation because of several reasons, e.g. an interface could 82 be disconnected or the communication path becomes unavailable due to 83 router failure. Many of the events, which cause the change of the 84 address set, are out of the scope of the MOBIKE protocol itself but 85 need an interaction with other protocols daemons locally at the end 86 host. 88 For MOBIKE to work, it is really important to know about the status 89 of the available addresses in order to make reasonable decisions. A 90 number of other protocols running on the end host might have various 91 information necessary to derive a decision whether to switch from one 92 preferred address to another or whether it is necessary to modify the 93 peer address set. 95 In this document, we therefore suggest to define an API that allows 96 protocol daemons to insert information (triggers) into a "database" 97 that can later be made available to the MOBIKE daemon. The API is 98 based on the BSD routing socket API in a similar fashion as PF_KEY 99 [1] extends the same API for generic key management usage. This 100 document therefore heavily focuses on the functionality offered by 101 the PF_KEY specification. 103 2. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in [2]. 109 Additionally, the following terms are introduced: 110 o Trigger: Information which is relevant for MOBIKE about an 111 address. 112 o Trigger Database (TDB): Collection of triggers which can be 113 accessed via the API defined in this document. 115 3. Trigger Classification 117 Many different events may cause a change in the address set used by 118 MOBIKE (see [3]). These events can be notified by many different 119 protocols running in kernel or user space. Since the reaction (if 120 any) on a given event depends on the type of the event, a 121 classification of these events is necessary. 123 As an example, we define the following triggers in this document: 125 Trigger type Value Description 126 ---------------------------+---------+--------------------------- 127 TDB_TTYPE_IF_ADDED | 1 | New interface added 128 TDB_TTYPE_IF_REMOVED | 2 | Interface removed 129 TDB_TTYPE_IF_ADDRCHANGED | 3 | Interface has changed its 130 | | address (e.g. new DHCP lease) 131 TDB_TTYPE_CONN_ESTABLISHED | 4 | e.g. dial-in network 132 | | has connected 133 TDB_TTYPE_CONN_LOST | 5 | connection to network lost 134 TDB_TTYPE_DEST_UNREACHABLE | 6 | e.g. ICMP packet received 136 A future version of this document will add more triggers and a more 137 detailed description of them. 139 4. API for the Trigger Database 141 To access the trigger database, an API is defined. For that purpose 142 the new network protocol family ID PF_TRIGGER has to be defined. The 143 operation of the API is analogue to the PF_KEY interface (see [1]). 145 To access the API, a socket of the family PF_TRIGGER has to be 146 created. To communicate with the Trigger Database, messages are sent 147 and received through the socket with the send and recv commands. Any 148 other commands like bind, connect, etc. are not supported and MUST 149 NOT have any effects on a socket of the PF_TRIGGER family. 151 The format of the messages is the following: Each message starts with 152 a fixed header. Appended to this header, there are some payloads 153 depending on the type of the message. The available message types 154 are described in Section 5. 156 Each time when a message is sent to the Trigger Database, it will 157 respond with a message of the same type. This response contains the 158 same payloads as transmitted to the Trigger Database, only some 159 additional information MAY be included (e.g., the Trigger Database 160 assigns an id to each trigger). 162 The normal operation works in the following way: A MOBIKE 163 implementation, which wants to be informed about every new trigger, 164 registers itself to the Trigger Database by sending a TDB_REGISTER 165 message. If a protocol daemon wants to add a new trigger, it sends a 166 TDB_ADD message to the Trigger Database including information that is 167 important for this new trigger. 169 The Trigger Database acknowledges this message with a TDB_ADD 170 response to the network protocol and with a TDB_NOTIFY message to the 171 registered MOBIKE implementation. This notify message contains some 172 information about the new trigger including its id. All information 173 available about the new trigger can be requested with a TDB_GET 174 message. 176 In a future version of this document, we will try to addd some 177 information about scenarios to better illustrate the interaction. 179 5. Supported Message Types 181 Several different message types can be sent to the Trigger Database 182 using a PF_TRIGGER socket. The message type is indicated by the 183 tdb_header_msgtype field that is part of the generic message header 184 (see Section 6) and can be one of the following values: 186 Message type Value Description 187 ---------------------------+---------+------------------------------ 188 TDB_ADD | 1 | Add a trigger to the 189 | | Trigger Database 190 TDB_GET | 2 | Get information about an 191 | | existing trigger. 192 TDB_DELETE | 3 | Delete a trigger from the 193 | | Trigger Database 194 TDB_REGISTER | 4 | Register an application 195 | | to receive a messages for 196 | | each new trigger added. 197 TDB_NOTIFY | 5 | A new trigger has been 198 | | added, deleted or updated. 199 TDB_MODIFY | 6 | Modify a trigger in the 200 | | Trigger Database 202 Each message type requires different payloads to be appended. Each 203 payload starts with a generic payload header followed by payload 204 specific data. The generic header has the following structure: 206 struct tdb_payload { 207 uint16_t tdb_payload_len; 208 uint16_t tdb_payload_type; 209 } __attribute__( ( packed ) ); 210 /* sizeof( struct tdb_payload ) == 4 */ 212 The tdb_payload_len field contains the length of the payload divided 213 by 8. The type of the payload is determined by the tdb_payload_type 214 field, which contains one of the following values: 216 Payload type Value Description 217 ---------------------------+---------+--------------------------- 218 TDB_PT_ADDRESS | 1 | The IP address of an IF 219 TDB_PT_TRIGGER | 2 | Trigger id, type, etc. 221 Details about the supported message types and their formats can be 222 found below: 224 TDB_ADD: 226 If an application or network protocol wants to add a new trigger, 227 it sends a TDB_ADD message to the Trigger Database. The new 228 trigger is stored in the Trigger Database and a corresponding 229 TDB_NOTIFY message that indicates that a new trigger has been 230 added is sent to all registered applications. 232 The format of the message is: 234 The TRIGGER payload indicates the type of the trigger and also 235 includes some trigger specific data. For many triggers, an 236 additional address payload is required. It contains, for example, 237 the new address for a TDB_TTYPE_IF_ADDRCHANGED trigger. 239 The response from the Trigger Database contains the same 240 information as the request: 242 TDB_DELETE: 244 A trigger, which is stored inside the Trigger Database, can be 245 deleted using the TDB_DELETE payload. 247 The format of the message is: 249 The Trigger Database responds with a message with the following 250 format: 252 In the response, the TRIGGER payload has all fields filled with 253 the correct values. 255 TDB_GET: 257 The TDB_GET message is used to request all available information 258 of a specified trigger. In the request the only information, 259 which has to be specified is the id of the trigger. 261 The format of the message is: 263 The Trigger Database responds with a message of the following 264 format: 266 In the response a fully initialized TRIGGER payload is present. 267 Additionally, an ADDRESS payload is present, if an address is 268 available for the specified trigger. 270 TDB_REGISTER: 272 An application, which is interested in each new trigger, can 273 register itself to the Trigger Database. After the application 274 has registered, it receives a message each time a new trigger has 275 been added to the database. 277 The format of the message is:
279 No additional payload has to be added. The Trigger Database 280 responds with a message of the same type and with the same 281 content, i.e. its format is
283 TDB_NOTIFY 285 An application that has registered itself to get informed about 286 the new triggers or updates to these triggers, receives a 287 TDB_NOTIFY message. The format of the message is the same as for 288 a TDB_ADD message. The only difference is that some field are 289 filled by the Trigger Database before sending the TDB_NOTIFY 290 message. 292 The format of the message is: 294 Since this message is sent by the Trigger Database itself, a 295 registered application MUST NOT respond to it. 297 TDB_MODIFY: 299 If an application or a network protocol wants to modify a new 300 trigger (because its status has changed), it sends a TDB_MODIFY 301 message to the Trigger Database. The new trigger is stored and a 302 corresponding TDB_NOTIFY message that indicates that an existing 303 trigger has been modified is sent to all registered applications. 305 The format of the message is: 307 The TRIGGER payload indicates the type of the trigger and also 308 includes some trigger specific data. 310 The response from the Trigger Database contains the same 311 information as the request: 313 6. Payload Format 315 HEADER: 317 Each message starts with the fixed header. It contains general 318 information about the message and determines, which payloads have 319 to be included in it. It has the following format: 321 struct tdb_header { 322 uint8_t tdb_header_version; 323 uint8_t tdb_header_msgtype; 324 uint8_t tdb_header_errno; 325 uint8_t tdb_header_reserved1; 326 uint16_t tdb_header_msglen; 327 uint16_t tdb_header_reserved2; 328 uint32_t tdb_header_seq; 329 uint32_t tdb_header_pid; 330 } __attribute__( ( packed ) ); 331 /* sizeof( struct tdb_header ) == 16 */ 333 The fields of this structure contain the following values: 335 tdb_header_version: The version of the used PF_TRIGGER interface. 336 This document specifies this API in version 1. 338 tdb_header_msgtype: This field contains the type of the message. 339 All possible values are listed in the table in Section 5. 341 tdb_header_errno: If an error occured while processing a request, 342 the response will only include the message header without any 343 payloads. The type of the error is indicated by the value in 344 this field. The values are taken from the error number 345 specification of the operating system (e.g. the errno.h file). 347 tdb_header_msglen: The length of the message divided by 8 is 348 stored into this field. 350 tdb_header_seq: This field contains the number of the last message 351 sent incremented by 1. 353 tdb_header_pid: The process id of the program sending the message. 354 If the message is generated inside the kernel, this value is 355 set to zero. 357 ADDRESS: 359 The ADDRESS payload is used to provide the IP address of an 360 interface to the Trigger Database or registered application. This 361 information is important for most triggers. But it might be 362 possible that there trigger types that do not need an ADDRESS 363 payload. 365 The format of the ADDRESS payload is: 367 struct tdb_address { 368 uint16_t tdb_address_len; 369 uint16_t tdb_address_pltype; 370 uint8_t tdb_address_prefixlen; 371 uint8_t tdb_address_reserved1; 372 uint16_t tdb_address_reserved2; 373 } __attribute__( ( packed ) ); 374 /* sizeof( struct tdb_address ) == 8 */ 376 Appended to the tdb_address structure is always a sockaddr 377 structure that includes the actual IP address. It is possible to 378 add an IPv4 or an IPv6 address. The fields of the tdb_address 379 structure contains the following values: 381 tdb_address_len: This field contains the length of the payload 382 including the sockaddr structure divided by 8. 384 tdb_address_pltype: The tdb_address_pltype field contains the 385 value TDB_PT_ADDRESS. 387 tdb_address_prefixlen: This field contains the prefix length of 388 the address. 390 TBD: Clarification about the prefix len needs to be provided in a 391 future document version. 393 TRIGGER: 395 The TRIGGER payload is used to provide all needed information 396 about a trigger itself, e.g. the trigger type, an id, etc. The 397 notation TRIGGER(*) indicates that only the id field is used to 398 identify the trigger and all other fields SHOULD be set to zero. 400 The format of the TRIGGER payload is the following: 402 struct tdb_trigger { 403 uint16_t tdb_trigger_len; 404 uint16_t tdb_trigger_pltype; 405 uint16_t tdb_trigger_type; 406 uint16_t tdb_trigger_reserved1; 407 uint32_t tdb_trigger_id; 408 uint32_t tdb_trigger_reserved2; 409 } __attribute__( ( packed ) ); 410 /* sizeof( struct tdb_trigger ) == 16 */ 412 This fields contain the following values: 414 tdb_address_len: This field contains the length of the payload 415 divided by 8. 417 tdb_address_pltype: This field contains the value TDB_PT_TRIGGER. 419 tdb_address_type: The type of the trigger is stored into this 420 field. All possible values are listed in the table in section 421 Section 3. 423 tdb_address_id: The id of a trigger is assigned by the Trigger 424 Database itself. In the message sent by userspace programs, 425 which do not know this value (e.g. for TDB_ADD messages), this 426 value MUST be set to zero. 428 Further information about a trigger might be necessary. This is 429 left for future investigation. 431 7. IANA Considerations 433 This document defines an IANA registry for the protocol family 434 PF_TRIGGER. 436 An IANA registry might be needed for the different trigger types (for 437 which examples are provided in Section 3). 439 8. Security Considerations 441 This document describes an API which allows information about IP 442 addresses to be obtained at a local host. A malicious application or 443 protocol daemon could disseminate wrong information. This would make 444 other protocols, such as MOBIKE, believe that the status of a 445 particular address has changed. This will likely lead to unexpected 446 protocol behavior, such as switching between addresses 447 back-and-forth. Hence, a certain trust has to be placed into the 448 applications and protocol daemons that are allowed to access the 449 database to insert, modify or delete triggers. Access control 450 mechanisms might enforce certain rights to use the API or parts of 451 it. 453 9. Acknowledgments 455 The authors would like to thank Murugaraj Shanmugam for his comments. 457 10. References 459 10.1 Normative References 461 [1] McDonald, D., Metz, C. and B. Phan, "PF_KEY Key Management API, 462 Version 2", RFC 2367, July 1998. 464 [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement 465 Levels", March 1997. 467 10.2 Informative References 469 [3] Kivinen, T. and H. Tschofenig, "Design of the MOBIKE protocol", 470 Internet-Draft draft-ietf-mobike-design-01, January 2005. 472 Authors' Addresses 474 Udo Schilcher 475 Siemens 476 Otto-Hahn-Ring 6 477 Munich, Bayern 81739 478 Germany 480 Email: USchilcher@siemens.com 482 Hannes Tschofenig 483 Siemens 484 Otto-Hahn-Ring 6 485 Munich, Bayern 81739 486 Germany 488 Email: Hannes.Tschofenig@siemens.com 490 Intellectual Property Statement 492 The IETF takes no position regarding the validity or scope of any 493 Intellectual Property Rights or other rights that might be claimed to 494 pertain to the implementation or use of the technology described in 495 this document or the extent to which any license under such rights 496 might or might not be available; nor does it represent that it has 497 made any independent effort to identify any such rights. Information 498 on the procedures with respect to rights in RFC documents can be 499 found in BCP 78 and BCP 79. 501 Copies of IPR disclosures made to the IETF Secretariat and any 502 assurances of licenses to be made available, or the result of an 503 attempt made to obtain a general license or permission for the use of 504 such proprietary rights by implementers or users of this 505 specification can be obtained from the IETF on-line IPR repository at 506 http://www.ietf.org/ipr. 508 The IETF invites any interested party to bring to its attention any 509 copyrights, patents or patent applications, or other proprietary 510 rights that may cover technology that may be required to implement 511 this standard. Please address the information to the IETF at 512 ietf-ipr@ietf.org. 514 Disclaimer of Validity 516 This document and the information contained herein are provided on an 517 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 518 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 519 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 520 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 521 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 522 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 524 Copyright Statement 526 Copyright (C) The Internet Society (2005). This document is subject 527 to the rights, licenses and restrictions contained in BCP 78, and 528 except as set forth therein, the authors retain all their rights. 530 Acknowledgment 532 Funding for the RFC Editor function is currently provided by the 533 Internet Society.