idnits 2.17.1 draft-ietf-mip6-mipext-advapi-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 18 longer pages, the longest (page 1) being 72 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 18 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** 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 476: '... As per Mobile IPv6 specification [2] a Home Agent MUST include...' RFC 2119 keyword, line 569: '...ader Type 2 extension header, one MUST...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 120 has weird spacing: '...ggested name ...' == Line 171 has weird spacing: '... struct ip6_m...' == Line 183 has weird spacing: '... struct ip6_m...' == Line 184 has weird spacing: '... ip6_mh ip6mh...' == Line 191 has weird spacing: '... struct ip6_...' == (42 more instances...) -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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) == Missing Reference: '16' is mentioned on line 381, but not defined == Missing Reference: '0' is mentioned on line 454, but not defined == Unused Reference: '3' is defined on line 711, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 3542 (ref. '1') ** Obsolete normative reference: RFC 2460 (ref. '3') (Obsoleted by RFC 8200) Summary: 7 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Samita Chakrabarti 3 Expires: August, 2004 Erik Nordmark 4 Sun Microsystems, Inc. 5 February, 2004 7 Extension to Sockets API for Mobile IPv6 8 10 Status of this Memo 12 This document is an Internet-Draft and is subject to 13 all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet Draft expires August, 2004. 33 Copyright Notice 35 Copyright (C) The Internet Society (2003). All Rights Reserved. 37 Abstract 39 This document describes data structures and API support for Mobile 40 IPv6 as an extension to Advanced Socket API support for IPv6. 42 Mobility Support in IPv6 introduces mobility protocol header 43 for IPv6. It is expected that future Mobile IPv6 applications 44 and implementations may need to access Mobility binding messages 45 and Return Routability messages for diagnostic, packet accounting 46 and local policy setting purposes. In order to provide portability 47 for Mobile IP applications that use sockets under IPv6, 48 standardization is needed for the Mobile IPv6 specific APIs. 50 This document provides mechanism for API access to retrieve and set 51 information for Mobility Header messages, Home address destination 52 options and Type 2 Routing header extension headers. It also discusses 53 the common data structures and definitions that might be used by 54 advanced Mobile IPv6 socket applications. 56 Table of Contents 58 1. Introduction ........................................... 3 60 2. Common Structures and Definitions ...................... 4 62 2.1 The Mobility Header Data Structures ................ 5 63 2.2 Mobility Header Constants .......................... 8 64 2.3 IPv6 Home Address Destination Option ................ 10 65 2.4 Type 2 Routing Header ............................... 10 66 2.5 ICMP Mobile IPv6 Messages ........................... 11 67 2.6 IPv6 Neighbor Discovery Changes ..................... 12 69 3. Access to Home Address Destination Option and Routing Headers 70 ................................ 14 71 3.1 Routing Header Access Functions ..................... 14 72 3.2 Home Address Destination Option Access Functions .... 14 74 4. Mobility Protocol Headers ............................... 15 76 4.1 Receiving and Sending Mobility Header Messages ..... 15 78 5. Protocols File ........................................... 17 80 6. IPv4-Mapped IPv6 Addresses ............................... 17 82 7. Security Considerations .................................. 17 84 8. References ............................................... 18 86 9. Acknowledgement .......................................... 18 88 10. Authors' Addresses ....................................... 18 90 1. Introduction 92 Mobility Support in IPv6 [2] defines a new mobility protocol header, 93 home address destination option and a new routing header type. 94 It is expected that Mobile IPv6 user-level implementations and some 95 applications will need to access and process these IPv6 extension 96 headers. This document is an extension to existing Advanced Sockets 97 API document [1]; it addresses the IPv6 Sockets API for Mobile IPv6 98 protocol support. The target applications for this socket API is 99 believed to be the debugging and diagnostic applications as well as 100 some policy applications which would like to receive a copy of 101 protocol information at the application layer. 103 This document can be divided into the following parts. 105 1. Definitions of constants and structures for C programs that 106 capture the Mobile IPv6 packet formats on the wire. A common 107 definition of these is useful at least for packet snooping 108 appplications. This is captured in section 2. 110 2. Notes on how to use the IPv6 Advanced API to access home address 111 options and type 2 routing headers. This is captured in 112 section 3. 114 3. Notes on how user-level applications can observe MH (Mobility 115 Header) packets using raw sockets (in section 4). The IPv6 RAW 116 socket interface described in this document, allows applications 117 to receive MH packets whether or not the systems MH processing 118 takes place in the "kernel" or at the "user space". 120 4. Suggested name for /etc/protocols (in section 5). 122 It is anticipated that Mobile IPv6 will be used widely from mobile 123 devices to Server and Routing platforms. Thus it is useful to have 124 a standard API for portability of Mobile IPv6 applications on a 125 wide variety of platforms and operating systems. 127 The packet information along with access to the extension headers 128 (Routing header and Destination options) are specified using the 129 "ancillary data" fields that were added to the 4.3BSD Reno sockets 130 API in 1990. The reason is that these ancillary data fields are 131 part of the Posix.1g standard and should therefore be adopted by 132 most vendors. This is in conformance with Advanced API for 133 IPv6 sockets [1]. 135 This document does not address application access to either the 136 authentication header or the encapsulating security payload header. 138 All examples in this document omit error checking in the favor of 139 brevity. 141 We note that many of the functions and socket options defined in this 142 document may have error returns that are not defined in this 143 document. Many of these possible error returns will be recognized 144 only as implementations proceed. 146 Datatypes in this document follow the Posix.1g format: intN_t means a 147 signed integer of exactly N bits (e.g., int16_t) and uintN_t means an 148 unsigned integer of exactly N bits (e.g., uint32_t). 150 This document provides guidelines on Mobile IPv6 socket applications 151 and believes that some other appropriate standardization body will 152 standardize the APIs along with other IPv6 advanced socket APIs. 154 2. Common Structures and Definitions 156 This API assumes that the fields in the protocol headers are left in 157 the network byte order, which is big-endian for the Internet 158 protocols. If not, then either these constants or the fields being 159 tested must be converted at run-time, using something like htons() or 160 htonl(). 162 A new header file : 164 2.1. The Mobility Header Data Structures 166 2.1.1 The ip6_mh Structure 168 The following structure is defined as a result of including 169 . This is fixed part of the mobility header. 171 struct ip6_mh { 172 uint8_t ip6mh_proto; /* NO_NXTHDR by default */ 173 uint8_t ip6mh_hdrlen; /* Header Len in unit of 8 Octets 174 excluding the first 8 Octets */ 175 uint8_t ip6mh_type; /* Type of Mobility Header */ 176 uint8_t ip6mh_reserved; /* Reserved */ 177 uint16_t ip6mh_cksum; /* Mobility Header Checksum */ 178 /* Followed by type specific messages */ 179 }; 181 2.1.2 Binding Refresh Request Mobility Message 183 struct ip6_mh_binding_request { 184 struct ip6_mh ip6mhbr_hdr; 185 uint16_t ip6mhbr_reserved; 186 /* Followed by optional Mobility Options */ 187 }; 189 2.1.3 Home Address Test Init (HoTI) Message 191 struct ip6_mh_home_test_init { 192 struct ip6_mh ip6mhhti_hdr; 193 uint16_t ip6mhhti_reserved; 194 uint32_t ip6mhhti_cookie[2]; /* 64 bit Cookie by MN */ 195 /* Followed by optional Mobility Options */ 196 }; 198 2.1.4 Care-of Address Test Init (CoTI) Message 200 struct ip6_mh_careof_test_init { 201 struct ip6_mh ip6mhcti_hdr; 202 uint16_t ip6mhcti_reserved; 203 uint32_t ip6mhcti_cookie[2]; /* 64 bit Cookie by MN */ 204 /* Followed by optional Mobility Options */ 205 }; 207 2.1.5 Home Address Test (HOT) Message 209 struct ip6_mh_home_test { 210 struct ip6_mh ip6mht_hdr; 211 uint16_t ip6mhht_nonce_index; 212 uint32_t ip6mhht_cookie[2]; /* Cookie from HOTI msg */ 213 uint32_t ip6mhht_keygen[2]; /* 64 Bit Key by CN */ 214 /* Followed by optional Mobility Options */ 215 }; 217 2.1.6 Care Of Address Test (COT) Message 219 struct ip6_mh_careof_test { 220 struct ip6_mh ip6mhct_hdr; 221 uint16_t ip6mhct_nonce_index; 222 uint32_t ip6mhct_cookie[2]; /* Cookie from COTI message */ 223 uint32_t ip6mhct_keygen[2]; /* 64bit key by CN */ 224 /* Followed by optional Mobility Options */ 225 }; 227 2.1.7 Binding Update Mobility Message 229 struct ip6_mh_binding_update { 230 struct ip6_mh ip6mhbu_hdr; 231 uint16_t ip6mhbu_seqno; /* Sequence Number */ 232 uint16_t ip6mhbu_flags; 233 uint16_t ip6mhbu_lifetime; /* Time in unit of 4 sec */ 234 /* Followed by optional Mobility Options */ 235 }; 237 /* Binding Update Flags, in network byte-order */ 238 #define IP6_MH_BU_ACK 0x8000 /* Request a binding ack */ 239 #define IP6_MH_BU_HOME 0x4000 /* Home Registration */ 240 #define IP6_MH_BU_LLOCAL 0x2000 /* Link-local compatibility */ 241 #define IP6_MH_BU_KEYM 0x1000 /* Key management mobility */ 243 2.1.8 Binding Acknowledgment Mobility Message 245 struct ip6_mh_binding_ack { 246 struct ip6_mh ip6mhba_hdr; 247 uint8_t ip6mhba_status; /* Status code */ 248 uint8_t ip6mhba_flags; 249 uint16_t ip6mhba_seqno; 250 uint16_t ip6mhba_lifetime; 251 /* Followed by optional Mobility Options */ 252 }; 254 /* Binding Acknowledgement Flags */ 255 #define IP6_MH_BA_KEYM 0x80 /* Key management mobility */ 257 2.1.9 Binding Error Mobility Message 259 struct ip6_mh_binding_error { 260 struct ip6_mh ip6mhbe_hdr; 261 uint8_t ip6mhbe_status; /* Error Status */ 262 uint8_t ip6mhbe_reserved; 263 struct in6_addr ip6mhbe_homeaddr; 264 /* Followed by optional Mobility Options */ 265 }; 267 2.1.10 Mobility Option TLV data structure 269 struct ip6_mh_opt { 270 uint8_t ip6mhopt_type; /* Option Type */ 271 uint8_t ip6mhopt_len; /* Option Length */ 272 /* Followed by variable length Option Data in bytes */ 273 }; 275 2.1.11 Mobility Option Data Structures 277 2.1.11.1 Binding Refresh Advice 279 struct ip6_mh_opt_refresh_advice { 280 uint8_t ip6mora_type; 281 uint8_t ip6mora_len; 282 uint16_t ip6mora_interval; /* Refresh interval in 4 sec */ 283 }; 285 2.1.11.2 Alternate Care-of Address 287 struct ip6_mh_opt_altcoa { 288 uint8_t ip6moa_type; 289 uint8_t ip6moa_len; 290 uint8_t ip6moa_addr[16]; /* Alternate Care-of Address */ 291 }; 293 2.1.11.3 Nonce Indices 295 struct ip6_mh_opt_nonce_index { 296 uint8_t ip6moni_type; 297 uint8_t ip6moni_len; 298 uint16_t ip6moni_home_nonce; 299 uint16_t ip6moni_coa_nonce; 300 }; 302 2.1.11.4 Binding Authorization Data 304 struct ip6_mh_opt_auth_data { 305 uint8_t ip6moad_type; 306 uint8_t ip6moad_len; 307 /* Followed by authentication data */ 308 }; 310 2.2 Mobility Header Constants 312 IPv6 Next Header Value for Mobility: 313 315 #define IPPROTO_MH 135 /* IPv6 Mobility Header: IANA */ 316 Mobility Header Message Types: 317 319 #define IP6_MH_TYPE_BRR 0 /* Binding Refresh Request */ 320 #define IP6_MH_TYPE_HOTI 1 /* HOTI Message */ 321 #define IP6_MH_TYPE_COTI 2 /* COTI Message */ 322 #define IP6_MH_TYPE_HOT 3 /* HOT Message */ 323 #define IP6_MH_TYPE_COT 4 /* COT Message */ 324 #define IP6_MH_TYPE_BU 5 /* Binding Update */ 325 #define IP6_MH_TYPE_BACK 6 /* Binding ACK */ 326 #define IP6_MH_TYPE_BERROR 7 /* Binding Error */ 328 Mobility Header Message Option Types: 329 331 #define IP6_MHOPT_PAD1 0x00 /* PAD1 */ 332 #define IP6_MHOPT_PADN 0x01 /* PADN */ 333 #define IP6_MHOPT_BREFRESH 0x02 /* Binding Refresh */ 334 #define IP6_MHOPT_ALTCOA 0x03 /* Alternate COA */ 335 #define IP6_MHOPT_NONCEID 0x04 /* Nonce Index */ 336 #define IP6_MHOPT_BAUTH 0x05 /* Binding Auth Data */ 338 Status values accompanied with Mobility Binding Acknowledgement: 339 341 #define IP6_MH_BAS_ACCEPTED 0 /* BU accepted */ 342 #define IP6_MH_BAS_PRFX_DISCOV 1 /* Accepted, but prefix 343 discovery Required */ 344 #define IP6_MH_BAS_UNSPECIFIED 128 /* Reason unspecified */ 345 #define IP6_MH_BAS_PROHIBIT 129 /* Administratively 346 prohibited */ 347 #define IP6_MH_BAS_INSUFFICIENT 130 /* Insufficient 348 resources */ 349 #define IP6_MH_BAS_HA_NOT_SUPPORTED 131 /* HA registration not 350 supported */ 351 #define IP6_MH_BAS_NOT_HOME_SUBNET 132 /* Not Home subnet */ 352 #define IP6_MH_BAS_NOT_HA 133 /* Not HA for this 353 mobile node */ 354 #define IP6_MH_BAS_DAD_FAILED 134 /* DAD failed */ 355 #define IP6_MH_BAS_SEQNO_BAD 135 /* Sequence number out 356 of range */ 358 #define IP6_MH_BAS_HOME_NI_EXPIRED 136 /* Expired Home nonce 359 index */ 360 #define IP6_MH_BAS_COA_NI_EXPIRED 137 /* Expired Care-of 361 nonce index */ 362 #define IP6_MH_BAS_NI_EXPIRED 138 /* Expired Nonce 363 Indices */ 364 #define IP6_MH_BAS_REG_NOT_ALLOWED 139 /* Registration type 365 change disallowed */ 367 Status values for the Binding Error mobility messages: 368 370 #define IP6_MH_BES_UNKNOWN_HAO 1 /* Unknown binding for HOA */ 371 #define IP6_MH_BES_UNKNOWN_MH 2 /* Unknown MH Type */ 373 2.3. IPv6 Home Address Destination Option 375 377 /* Home Address Destination Option */ 378 struct ip6_opt_home_address { 379 uint8_t ip6oha_type; 380 uint8_t ip6oha_len; 381 uint8_t ip6oha_addr[16]; /* Home Address */ 382 }; 384 Option Type Definition: 386 #define IP6OPT_HOME_ADDRESS 0xc9 /* 11 0 01001 */ 388 2.4 Type 2 Routing Header 390 392 /* Type 2 Routing header for Mobile IPv6 */ 393 struct ip6_rthdr2 { 394 uint8_t ip6r2_nxt; /* next header */ 395 uint8_t ip6r2_len; /* length : always 2 */ 396 uint8_t ip6r2_type; /* always 2 */ 397 uint8_t ip6r2_segleft; /* segments left: always 1 */ 398 uint32_t ip6r2_reserved; /* reserved field */ 399 struct in6_addr ip6r2_homeaddr; /* Home Address */ 400 }; 402 2.5 New ICMP Messages for Mobile IPv6 404 ICMP message types and definitions for Mobile IPv6 are defined in 405 407 #define MIP6_HA_DISCOVERY_REQUEST 150 408 #define MIP6_HA_DISCOVERY_REPLY 151 409 #define MIP6_PREFIX_SOLICIT 152 410 #define MIP6_PREFIX_ADVERT 153 412 The following data structures can be used for the ICMP message 413 types discussed in section 6.5 through 6.8 in the base Mobile 414 IPv6 [2] specification. 416 struct mip6_dhaad_req { /* Dynamic HA Address Discovery */ 417 struct icmp6_hdr mip6_dhreq_hdr; 418 }; 420 #define mip6_dhreq_type mip6_dhreq_hdr.icmp6_type 421 #define mip6_dhreq_code mip6_dhreq_hdr.icmp6_code 422 #define mip6_dhreq_cksum mip6_dhreq_hdr.icmp6_cksum 423 #define mip6_dhreq_id mip6_dhreq_hdr.icmp6_data16[0] 424 #define mip6_dhreq_reserved mip6_dhreq_hdr.icmp6_data16[1] 426 struct mip6_dhaad_rep { /* HA Address Discovery Reply */ 427 struct icmp6_hdr mip6_dhrep_hdr; 428 /* Followed by Home Agent IPv6 addresses */ 429 }; 431 #define mip6_dhrep_type mip6_dhrep_hdr.icmp6_type 432 #define mip6_dhrep_code mip6_dhrep_hdr.icmp6_code 433 #define mip6_dhrep_cksum mip6_dhrep_hdr.icmp6_cksum 434 #define mip6_dhrep_id mip6_dhrep_hdr.icmp6_data16[0] 435 #define mip6_dhrep_reserved mip6_dhrep_hdr.icmp6_data16[1] 437 struct mip6_prefix_solicit { /* Mobile Prefix Solicitation */ 438 struct icmp6_hdr mip6_ps_hdr; 439 }; 441 #define mip6_ps_type mip6_ps_hdr.icmp6_type 442 #define mip6_ps_code mip6_ps_hdr.icmp6_code 443 #define mip6_ps_cksum mip6_ps_hdr.icmp6_cksum 444 #define mip6_ps_id mip6_ps_hdr.icmp6_data16[0] 445 #define mip6_ps_reserved mip6_ps_hdr.icmp6_data16[1] 446 struct mip6_prefix_advert { /* Mobile Prefix Adverisements */ 447 struct icmp6_hdr mip6_pa_hdr; 448 /* Followed by one or more PI options */ 449 }; 451 #define mip6_pa_type mip6_pa_hdr.icmp6_type 452 #define mip6_pa_code mip6_pa_hdr.icmp6_code 453 #define mip6_pa_cksum mip6_pa_hdr.icmp6_cksum 454 #define mip6_pa_id mip6_pa_hdr.icmp6_data16[0] 455 #define mip6_pa_flags_reserved mip6_pa_hdr.icmp6_data16[1] 457 #define MIP6_PA_FLAG_MANAGED 0x8000 458 #define MIP6_PA_FLAG_OTHER 0x4000 460 Prefix options are defined in IPv6 Advanced Socket API [1]. 461 Mobile IPv6 Base specification [2] describes the modified 462 behavior in 'Modifications to IPv6 Neighbor Discovery' section. 463 Prefix Options for Mobile IP are defined in the following section. 465 2.6 IPv6 Neighbor Discovery Changes 467 IPv6 Neighbor Discovery changes are also defined in 468 470 New 'Home Agent' flag in router advertisement: 471 #define ND_RA_FLAG_HOMEAGENT 0x20 /* Home Agent flag in RA */ 473 New Router flag with prefix information of the home agent: 474 #define ND_OPT_PI_FLAG_ROUTER 0x20 /* Router flag in PI */ 476 As per Mobile IPv6 specification [2] a Home Agent MUST include 477 at least one prefix option with the Rouer Address (R) bit set. 478 Advanced Socket API [1] defines data structure for prefix option 479 as follows: 481 struct nd_opt_prefix_info { /* prefix information */ 482 uint8_t nd_opt_pi_type; 483 uint8_t nd_opt_pi_len; 484 uint8_t nd_opt_pi_prefix_len; 485 uint8_t nd_opt_pi_flags_reserved; 486 uint32_t nd_opt_pi_valid_time; 487 uint32_t nd_opt_pi_preferred_time; 488 uint32_t nd_opt_pi_reserved2; 489 struct in6_addr nd_opt_pi_prefix; 490 }; 492 New advertisement interval option and home agent information 493 options are defined in Mobile IPv6 [2] base specification. 495 struct nd_opt_adv_interval { /* Advertisement interval option */ 496 uint8_t nd_opt_ai_type; 497 uint8_t nd_opt_ai_len; 498 uint16_t nd_opt_ai_reserved; 499 uint32_t nd_opt_ai_interval; 500 }; 502 The option types for the new Mobile IPv6 specific options: 504 #define ND_OPT_ADV_INTERVAL 7 /* Adv Interval Option */ 505 #define ND_OPT_HA_INFORMATION 8 /* HA Information option */ 507 struct nd_opt_homeagent_info { /* Home Agent information */ 508 uint8_t nd_opt_hai_type; 509 uint8_t nd_opt_hai_len; 510 uint16_t nd_opt_hai_reserved; 511 uint16_t nd_opt_hai_preference; 512 uint16_t nd_opt_hai_lifetime; 513 }; 515 3. Access to Home Address Destination Option and Routing Headers 517 Applications that need to be able to access home address destination 518 option and routing header type 2 information should use the same 519 mechanism defined in Advanced Sockets API for IPv6 in section 4. 521 In order to receive Home Address destination option or route header 522 type 2 extension header, application must call setsockopt() to turn 523 on the corresponding flag: 525 int on = 1; 527 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); 528 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); 530 When any of these options are enabled, the corresponding data is 531 returned as control information by recvmsg(), as one or more 532 ancillary data objects. Receiving the above information for TCP 533 applications is not defined in this document (see section 4.1 of 534 Advanced Sockets API for IPv6[1]. 536 For sending home address destination option, ancillary data can be 537 used to specify the option content for a single datagram. This 538 only applies to datagram and raw sockets; not to TCP sockets. 539 Advanced API [1] document restricts one IPV6_xxx ancillary data 540 object for a particular extension header in the control buffer. 541 Thus there would be a single ancillary data object for Home address 542 destination option in a ancillary data buffer. If the kernel 543 implementation supports this API, it is responsible for extracting 544 the Home address destination option data object and placing it as 545 destination option extension header in compliance with section 546 6.3 of Mobile IPv6 [2] base specification. 548 For TCP data packets with home-address destination option may be 549 used with "sticky" option for all transmitted packets. However, 550 at this point, it is unknown why an application would want to 551 set home-address option or Route Header Type 2 extension header 552 along with its data packets as Mobile IPv6 protocol takes care of 553 them transparently at the protocol stack. 555 However, the following socket option parameters and cmsghdr fields 556 may be used for sending. 558 opt level/ optname/ optval/ 559 cmsg_level cmsg_type cmsg_data[] 560 ------------ ------------ ------------------------ 561 IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure 562 IPPROTO_IPV6 IPV6_RTHDR ip6_rthdr structure 564 Some IPv6 implementations may support "sticky" options [1] for IPv6 565 destination option for datagram sockets. 567 3.1 Routing Header access functions 569 While accessing Routing header Type 2 extension header, one MUST 570 use type = 2 and segment = 1. The following functions are supported 571 for Mobile IPv6 applications for sending and receiving Routing 572 Header Type 2 headers: 574 size_t inet6_rth_space(int type, int segments); 575 void *inet6_rth_init(void *bp, int bp_len, int type, int segments); 576 int inet6_rth_add(void *bp, const struct in6_addr *addr); 577 int inet6_rth_segments(const void *bp); 578 struct in6_addr *inet6_rth_getaddr(const void *bp, int index); 580 NOTE: Reversing operation is not possible using Route Header Type 2 581 extension header. 583 Detail description and examples of accessing a IPv6 Routing Header 584 are discussed in Advanced API for IPv6 Sockets [1]. 586 3.2 Home Address Destination Option access functions 588 The application must enable the IPV6_RECVDSTOPTS socket option in 589 order to receive the home address destination option: 591 int on = 1; 592 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); 594 Each Destination option header is returned as one ancillary data 595 object described by a cmsghdr structure with cmsg_level set to 596 IPPROTO_IPV6 and cmsg_type set to IPV6_DSTOPTS. 598 These options are then processed by calling the inet6_opt_next(), 599 inet6_opt_find(), and inet6_opt_get_value() functions as defined 600 in Advanced API for IPv6 sockets [1]. 602 This document assumes that Mobile IPv6 applications will not be 603 allowed to send Home Address Destination Option from the 604 application level, as Mobile IPv6 kernel takes care of sending 605 home-address option and routing header type 2. 607 The Destination options are normally constructed using the 608 inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and 609 inet6_opt_set_val() functions, described in Section 10 of IPv6 610 Advanced API sockets [1]. 612 4. Mobility Protocol Headers 614 Mobile IPv6 [2] defines a new IPv6 protocol header to carry mobility 615 messages between Mobile Nodes, Home Agents and Correspondent Nodes. 616 These protocol headers carry Mobile IPv6 Binding messages as well as 617 Return Routability [2] messages. Currently the specification [2] 618 does not allow transport packets (piggybacking) along with the 619 mobility messages. Thus the mobility protocol header can be 620 accessed through a IPv6 RAW socket. A IPv6 RAW socket that is opened 621 for protocol IPPROTO_MH should always be able to see all the MH 622 (Mobility Header) packets. It is possible that future applications 623 may implement part of Mobile IPv6 signal processing at the 624 application level. Having a RAW socket interface may also enable 625 an application to execute the Return Routability protocol or other 626 future authentication protocol involving mobility header at the user 627 level. 629 4.1 Receiving and Sending Mobility Header Messages 631 This specification recommends IPv6 RAW sockets mechanism to send 632 and receive Mobility Header (MH) packets. The behavior is similar to 633 ICMPV6 processing, where kernel passes a copy of the mobility header 634 packet to the receiving socket. Depending on the implementation 635 kernel may process the mobility header as well in addition to passing 636 the mobility header to the application. 637 In order to comply with the restriction in Advance API for IPv6 [1] 638 sockets, applications should set IPV6_CHECKSUM socket option with 639 IPPROTO_MH protocol RAW Sockets. However, a Mobile IPv6 implementa- 640 tion that supports Mobile IPv6 API, must implement mobility header 641 API checksum calculation by default at the kernel for both incoming 642 and outbound path. A Mobile IPv6 implementation must not return error 643 on IPV6_CHECKSUM socket option setting, even if the socket option is 644 a NO-OP function for that implementation because it verifies the 645 checksum at the kernel level. Mobility Header checksum procedure 646 is described in Mobile IPv6 Protocol [2] specification. 647 Again, it is recommended that the applications set the IPV6_CHECKSUM 648 socket option along with the RAW sockets for IPPROTO_MH protocol, 649 for application portability. 651 As an example, a program that wants to send or receive mobility 652 header protocol(MH), could open a socket as following: 654 fd = socket(AF_INET6, SOCK_RAW, IPPROTO_MH); 656 int offset = 4; 657 setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, 658 sizeof(offset)); 660 For example, if an implementation likes to handle HOTI/HOT and 661 COTI/COT message processing, it can do so by using IPv6 RAW Sockets 662 for IPPROTO_MH at the application layer. 663 The same application may also set IPV6_RECVDSTOPTS socket option for 664 receiving home address option in a binding update [2] from the mobile 665 node. 667 5. Protocols File 669 Many hosts provide the file /etc/protocols that contains the names 670 of the various IP protocols and their protocol numbers. The protocol 671 numbers are obtained through function getprotoXXX() functions. 673 The following addition should be made to the /etc/protocols file, 674 in addition to what is defined in section 2.4 of Advanced Sockets 675 API for IPv6 [1]. 677 The protocol number for Mobility header: 678 (http://www.iana.org/assignments/protocol-numbers) 680 ipv6-mh 135 # Mobility Protocol Header 682 6. IPv4-Mapped IPv6 Addresses 684 The same rule applies as described in section 13 of IPv6 Advanced 685 API for Sockets [1]. Thus processing of IPv4-mapped IPv6 addresses 686 for the Mobile IPv6 specific socket options are out of scope of this 687 document. 689 7. Security Considerations 691 The setting of Home Address Destination option and route header 692 Type 2 IPV6_RTHDR socket option may not be allowed at the 693 application level in order to prevent denial-of-service attacks 694 or man in the middle attacks by hackers. 695 Sending and receiving of mobility header messages are possible by 696 IPv6 RAW sockets. Thus it is assumed that this operation is only 697 possible by priviledged users. However, this API does not prevent 698 the existing security threat from a hacker by sending bogus mobility 699 header or other IPv6 packets using home-address option and Type 2 700 routing extension header. 702 8. References 704 [1] Stevens, W. R, Thomas, M., Nordmark, E., Jinmei, T., "Advanced 705 Sockets API for IPv6", RFC 3542, May 2003 706 April 19, 2002. 708 [2] Johnson, D., Perkins, C., Arkko, J., "Mobility Support in IPv6" 709 draft-ietf-mobileip-ipv6-24.txt, June, 2003. 711 [3] Deering, S., Hinden, R., "Internet Protocol, Version 6 712 (IPv6), Specification", RFC 2460, Dec. 1998. 714 9. Acknowledgement 716 Thanks to Brian Haley for the thorough review of this draft and many 717 helpful comments. Keiichi Shima, Alexandru Petrescu, Ryuji Wakikawa, 718 Vijay Devarapalli, Jim Bound, Suvidh Mathur and other mobile-ip 719 working group members provided valuable input during the API design 720 discussion. Vladislav Yasevich recommended default checksum 721 calculation for mobility header API at the kernel level. 723 10. Authors' Addresses 725 Samita Chakrabarti 726 Sun Microsystems, Inc. 727 4150 Network Circle 728 Santa Clara, CA 95054, USA 729 Email: samita.chakrabarti@Sun.com 731 Erik Nordmark 732 Sun Microsystems Laboratories 733 180, avenue de l'Europe 734 38334 SAINT ISMIER Cedex, France 735 Email: Erik.Nordmark@sun.com