idnits 2.17.1 draft-ietf-mip6-mipext-advapi-01.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 1 longer page, the longest (page 15) being 61 lines 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 17 instances of lines with control characters in the document. ** 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 478: '... As per Mobile IPv6 specification [2] a Home Agent MUST include...' RFC 2119 keyword, line 571: '...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 122 has weird spacing: '...ggested name ...' == Line 173 has weird spacing: '... struct ip6_m...' == Line 185 has weird spacing: '... struct ip6_m...' == Line 186 has weird spacing: '... ip6_mh ip6mh...' == Line 193 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: '12' is mentioned on line 309, but not defined == Missing Reference: '16' is mentioned on line 383, but not defined == Missing Reference: '0' is mentioned on line 456, but not defined == Unused Reference: '3' is defined on line 724, 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: October, 2004 Erik Nordmark 4 Sun Microsystems, Inc. 5 April, 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 October, 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 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. Changes from last revision ............................... 18 90 11. Authors' Addresses ....................................... 19 92 1. Introduction 94 Mobility Support in IPv6 [2] defines a new mobility protocol header, 95 home address destination option and a new routing header type. 96 It is expected that Mobile IPv6 user-level implementations and some 97 applications will need to access and process these IPv6 extension 98 headers. This document is an extension to existing Advanced Sockets 99 API document [1]; it addresses the IPv6 Sockets API for Mobile IPv6 100 protocol support. The target applications for this socket API is 101 believed to be the debugging and diagnostic applications as well as 102 some policy applications which would like to receive a copy of 103 protocol information at the application layer. 105 This document can be divided into the following parts. 107 1. Definitions of constants and structures for C programs that 108 capture the Mobile IPv6 packet formats on the wire. A common 109 definition of these is useful at least for packet snooping 110 appplications. This is captured in section 2. 112 2. Notes on how to use the IPv6 Advanced API to access home address 113 options and type 2 routing headers. This is captured in 114 section 3. 116 3. Notes on how user-level applications can observe MH (Mobility 117 Header) packets using raw sockets (in section 4). The IPv6 RAW 118 socket interface described in this document, allows applications 119 to receive MH packets whether or not the systems MH processing 120 takes place in the "kernel" or at the "user space". 122 4. Suggested name for /etc/protocols (in section 5). 124 It is anticipated that Mobile IPv6 will be used widely from mobile 125 devices to Server and Routing platforms. Thus it is useful to have 126 a standard API for portability of Mobile IPv6 applications on a 127 wide variety of platforms and operating systems. 129 The packet information along with access to the extension headers 130 (Routing header and Destination options) are specified using the 131 "ancillary data" fields that were added to the 4.3BSD Reno sockets 132 API in 1990. The reason is that these ancillary data fields are 133 part of the Posix.1g standard and should therefore be adopted by 134 most vendors. This is in conformance with Advanced API for 135 IPv6 sockets [1]. 137 This document does not address application access to either the 138 authentication header or the encapsulating security payload header. 140 All examples in this document omit error checking in the favor of 141 brevity. 143 We note that many of the functions and socket options defined in this 144 document may have error returns that are not defined in this 145 document. Many of these possible error returns will be recognized 146 only as implementations proceed. 148 Datatypes in this document follow the Posix.1g format: intN_t means a 149 signed integer of exactly N bits (e.g., int16_t) and uintN_t means an 150 unsigned integer of exactly N bits (e.g., uint32_t). 152 This document provides guidelines on Mobile IPv6 socket applications 153 and believes that some other appropriate standardization body will 154 standardize the APIs along with other IPv6 advanced socket APIs. 156 2. Common Structures and Definitions 158 This API assumes that the fields in the protocol headers are left in 159 the network byte order, which is big-endian for the Internet 160 protocols. If not, then either these constants or the fields being 161 tested must be converted at run-time, using something like htons() or 162 htonl(). 164 A new header file : 166 2.1. The Mobility Header Data Structures 168 2.1.1 The ip6_mh Structure 170 The following structure is defined as a result of including 171 . This is fixed part of the mobility header. 173 struct ip6_mh { 174 uint8_t ip6mh_proto; /* NO_NXTHDR by default */ 175 uint8_t ip6mh_hdrlen; /* Header Len in unit of 8 Octets 176 excluding the first 8 Octets */ 177 uint8_t ip6mh_type; /* Type of Mobility Header */ 178 uint8_t ip6mh_reserved; /* Reserved */ 179 uint16_t ip6mh_cksum; /* Mobility Header Checksum */ 180 /* Followed by type specific messages */ 181 }; 183 2.1.2 Binding Refresh Request Mobility Message 185 struct ip6_mh_binding_request { 186 struct ip6_mh ip6mhbr_hdr; 187 uint16_t ip6mhbr_reserved; 188 /* Followed by optional Mobility Options */ 189 }; 191 2.1.3 Home Address Test Init (HoTI) Message 193 struct ip6_mh_home_test_init { 194 struct ip6_mh ip6mhhti_hdr; 195 uint16_t ip6mhhti_reserved; 196 uint32_t ip6mhhti_cookie[2]; /* 64 bit Cookie by MN */ 197 /* Followed by optional Mobility Options */ 198 }; 200 2.1.4 Care-of Address Test Init (CoTI) Message 202 struct ip6_mh_careof_test_init { 203 struct ip6_mh ip6mhcti_hdr; 204 uint16_t ip6mhcti_reserved; 205 uint32_t ip6mhcti_cookie[2]; /* 64 bit Cookie by MN */ 206 /* Followed by optional Mobility Options */ 207 }; 209 2.1.5 Home Address Test (HOT) Message 211 struct ip6_mh_home_test { 212 struct ip6_mh ip6mht_hdr; 213 uint16_t ip6mhht_nonce_index; 214 uint32_t ip6mhht_cookie[2]; /* Cookie from HOTI msg */ 215 uint32_t ip6mhht_keygen[2]; /* 64 Bit Key by CN */ 216 /* Followed by optional Mobility Options */ 217 }; 219 2.1.6 Care Of Address Test (COT) Message 221 struct ip6_mh_careof_test { 222 struct ip6_mh ip6mhct_hdr; 223 uint16_t ip6mhct_nonce_index; 224 uint32_t ip6mhct_cookie[2]; /* Cookie from COTI message */ 225 uint32_t ip6mhct_keygen[2]; /* 64bit key by CN */ 226 /* Followed by optional Mobility Options */ 227 }; 229 2.1.7 Binding Update Mobility Message 231 struct ip6_mh_binding_update { 232 struct ip6_mh ip6mhbu_hdr; 233 uint16_t ip6mhbu_seqno; /* Sequence Number */ 234 uint16_t ip6mhbu_flags; 235 uint16_t ip6mhbu_lifetime; /* Time in unit of 4 sec */ 236 /* Followed by optional Mobility Options */ 237 }; 239 /* Binding Update Flags, in network byte-order */ 240 #define IP6_MH_BU_ACK 0x8000 /* Request a binding ack */ 241 #define IP6_MH_BU_HOME 0x4000 /* Home Registration */ 242 #define IP6_MH_BU_LLOCAL 0x2000 /* Link-local compatibility */ 243 #define IP6_MH_BU_KEYM 0x1000 /* Key management mobility */ 245 2.1.8 Binding Acknowledgment Mobility Message 247 struct ip6_mh_binding_ack { 248 struct ip6_mh ip6mhba_hdr; 249 uint8_t ip6mhba_status; /* Status code */ 250 uint8_t ip6mhba_flags; 251 uint16_t ip6mhba_seqno; 252 uint16_t ip6mhba_lifetime; 253 /* Followed by optional Mobility Options */ 254 }; 256 /* Binding Acknowledgement Flags */ 257 #define IP6_MH_BA_KEYM 0x80 /* Key management mobility */ 259 2.1.9 Binding Error Mobility Message 261 struct ip6_mh_binding_error { 262 struct ip6_mh ip6mhbe_hdr; 263 uint8_t ip6mhbe_status; /* Error Status */ 264 uint8_t ip6mhbe_reserved; 265 struct in6_addr ip6mhbe_homeaddr; 266 /* Followed by optional Mobility Options */ 267 }; 269 2.1.10 Mobility Option TLV data structure 271 struct ip6_mh_opt { 272 uint8_t ip6mhopt_type; /* Option Type */ 273 uint8_t ip6mhopt_len; /* Option Length */ 274 /* Followed by variable length Option Data in bytes */ 275 }; 277 2.1.11 Mobility Option Data Structures 279 2.1.11.1 Binding Refresh Advice 281 struct ip6_mh_opt_refresh_advice { 282 uint8_t ip6mora_type; 283 uint8_t ip6mora_len; 284 uint16_t ip6mora_interval; /* Refresh interval in 4 sec */ 285 }; 287 2.1.11.2 Alternate Care-of Address 289 struct ip6_mh_opt_altcoa { 290 uint8_t ip6moa_type; 291 uint8_t ip6moa_len; 292 struct in6_addr ip6moa_addr; /* Alternate Care-of Address */ 293 }; 295 2.1.11.3 Nonce Indices 297 struct ip6_mh_opt_nonce_index { 298 uint8_t ip6moni_type; 299 uint8_t ip6moni_len; 300 uint16_t ip6moni_home_nonce; 301 uint16_t ip6moni_coa_nonce; 302 }; 304 2.1.11.4 Binding Authorization Data 306 struct ip6_mh_opt_auth_data { 307 uint8_t ip6moad_type; 308 uint8_t ip6moad_len; 309 uint8_t ip6moad_data[12]; 310 }; 312 2.2 Mobility Header Constants 314 IPv6 Next Header Value for Mobility: 315 317 #define IPPROTO_MH 135 /* IPv6 Mobility Header: IANA */ 318 Mobility Header Message Types: 319 321 #define IP6_MH_TYPE_BRR 0 /* Binding Refresh Request */ 322 #define IP6_MH_TYPE_HOTI 1 /* HOTI Message */ 323 #define IP6_MH_TYPE_COTI 2 /* COTI Message */ 324 #define IP6_MH_TYPE_HOT 3 /* HOT Message */ 325 #define IP6_MH_TYPE_COT 4 /* COT Message */ 326 #define IP6_MH_TYPE_BU 5 /* Binding Update */ 327 #define IP6_MH_TYPE_BACK 6 /* Binding ACK */ 328 #define IP6_MH_TYPE_BERROR 7 /* Binding Error */ 330 Mobility Header Message Option Types: 331 333 #define IP6_MHOPT_PAD1 0x00 /* PAD1 */ 334 #define IP6_MHOPT_PADN 0x01 /* PADN */ 335 #define IP6_MHOPT_BREFRESH 0x02 /* Binding Refresh */ 336 #define IP6_MHOPT_ALTCOA 0x03 /* Alternate COA */ 337 #define IP6_MHOPT_NONCEID 0x04 /* Nonce Index */ 338 #define IP6_MHOPT_BAUTH 0x05 /* Binding Auth Data */ 340 Status values accompanied with Mobility Binding Acknowledgement: 341 343 #define IP6_MH_BAS_ACCEPTED 0 /* BU accepted */ 344 #define IP6_MH_BAS_PRFX_DISCOV 1 /* Accepted, but prefix 345 discovery Required */ 346 #define IP6_MH_BAS_UNSPECIFIED 128 /* Reason unspecified */ 347 #define IP6_MH_BAS_PROHIBIT 129 /* Administratively 348 prohibited */ 349 #define IP6_MH_BAS_INSUFFICIENT 130 /* Insufficient 350 resources */ 351 #define IP6_MH_BAS_HA_NOT_SUPPORTED 131 /* HA registration not 352 supported */ 353 #define IP6_MH_BAS_NOT_HOME_SUBNET 132 /* Not Home subnet */ 354 #define IP6_MH_BAS_NOT_HA 133 /* Not HA for this 355 mobile node */ 356 #define IP6_MH_BAS_DAD_FAILED 134 /* DAD failed */ 357 #define IP6_MH_BAS_SEQNO_BAD 135 /* Sequence number out 358 of range */ 360 #define IP6_MH_BAS_HOME_NI_EXPIRED 136 /* Expired Home nonce 361 index */ 362 #define IP6_MH_BAS_COA_NI_EXPIRED 137 /* Expired Care-of 363 nonce index */ 364 #define IP6_MH_BAS_NI_EXPIRED 138 /* Expired Nonce 365 Indices */ 366 #define IP6_MH_BAS_REG_NOT_ALLOWED 139 /* Registration type 367 change disallowed */ 369 Status values for the Binding Error mobility messages: 370 372 #define IP6_MH_BES_UNKNOWN_HAO 1 /* Unknown binding for HOA */ 373 #define IP6_MH_BES_UNKNOWN_MH 2 /* Unknown MH Type */ 375 2.3. IPv6 Home Address Destination Option 377 379 /* Home Address Destination Option */ 380 struct ip6_opt_home_address { 381 uint8_t ip6oha_type; 382 uint8_t ip6oha_len; 383 uint8_t ip6oha_addr[16]; /* Home Address */ 384 }; 386 Option Type Definition: 388 #define IP6OPT_HOME_ADDRESS 0xc9 /* 11 0 01001 */ 390 2.4 Type 2 Routing Header 392 394 /* Type 2 Routing header for Mobile IPv6 */ 395 struct ip6_rthdr2 { 396 uint8_t ip6r2_nxt; /* next header */ 397 uint8_t ip6r2_len; /* length : always 2 */ 398 uint8_t ip6r2_type; /* always 2 */ 399 uint8_t ip6r2_segleft; /* segments left: always 1 */ 400 uint32_t ip6r2_reserved; /* reserved field */ 401 struct in6_addr ip6r2_homeaddr; /* Home Address */ 402 }; 404 2.5 New ICMP Messages for Mobile IPv6 406 ICMP message types and definitions for Mobile IPv6 are defined in 407 409 #define MIP6_HA_DISCOVERY_REQUEST 150 410 #define MIP6_HA_DISCOVERY_REPLY 151 411 #define MIP6_PREFIX_SOLICIT 152 412 #define MIP6_PREFIX_ADVERT 153 414 The following data structures can be used for the ICMP message 415 types discussed in section 6.5 through 6.8 in the base Mobile 416 IPv6 [2] specification. 418 struct mip6_dhaad_req { /* Dynamic HA Address Discovery */ 419 struct icmp6_hdr mip6_dhreq_hdr; 420 }; 422 #define mip6_dhreq_type mip6_dhreq_hdr.icmp6_type 423 #define mip6_dhreq_code mip6_dhreq_hdr.icmp6_code 424 #define mip6_dhreq_cksum mip6_dhreq_hdr.icmp6_cksum 425 #define mip6_dhreq_id mip6_dhreq_hdr.icmp6_data16[0] 426 #define mip6_dhreq_reserved mip6_dhreq_hdr.icmp6_data16[1] 428 struct mip6_dhaad_rep { /* HA Address Discovery Reply */ 429 struct icmp6_hdr mip6_dhrep_hdr; 430 /* Followed by Home Agent IPv6 addresses */ 431 }; 433 #define mip6_dhrep_type mip6_dhrep_hdr.icmp6_type 434 #define mip6_dhrep_code mip6_dhrep_hdr.icmp6_code 435 #define mip6_dhrep_cksum mip6_dhrep_hdr.icmp6_cksum 436 #define mip6_dhrep_id mip6_dhrep_hdr.icmp6_data16[0] 437 #define mip6_dhrep_reserved mip6_dhrep_hdr.icmp6_data16[1] 439 struct mip6_prefix_solicit { /* Mobile Prefix Solicitation */ 440 struct icmp6_hdr mip6_ps_hdr; 441 }; 443 #define mip6_ps_type mip6_ps_hdr.icmp6_type 444 #define mip6_ps_code mip6_ps_hdr.icmp6_code 445 #define mip6_ps_cksum mip6_ps_hdr.icmp6_cksum 446 #define mip6_ps_id mip6_ps_hdr.icmp6_data16[0] 447 #define mip6_ps_reserved mip6_ps_hdr.icmp6_data16[1] 448 struct mip6_prefix_advert { /* Mobile Prefix Adverisements */ 449 struct icmp6_hdr mip6_pa_hdr; 450 /* Followed by one or more PI options */ 451 }; 453 #define mip6_pa_type mip6_pa_hdr.icmp6_type 454 #define mip6_pa_code mip6_pa_hdr.icmp6_code 455 #define mip6_pa_cksum mip6_pa_hdr.icmp6_cksum 456 #define mip6_pa_id mip6_pa_hdr.icmp6_data16[0] 457 #define mip6_pa_flags_reserved mip6_pa_hdr.icmp6_data16[1] 459 #define MIP6_PA_FLAG_MANAGED 0x8000 460 #define MIP6_PA_FLAG_OTHER 0x4000 462 Prefix options are defined in IPv6 Advanced Socket API [1]. 463 Mobile IPv6 Base specification [2] describes the modified 464 behavior in 'Modifications to IPv6 Neighbor Discovery' section. 465 Prefix Options for Mobile IP are defined in the following section. 467 2.6 IPv6 Neighbor Discovery Changes 469 IPv6 Neighbor Discovery changes are also defined in 470 472 New 'Home Agent' flag in router advertisement: 473 #define ND_RA_FLAG_HOMEAGENT 0x20 /* Home Agent flag in RA */ 475 New Router flag with prefix information of the home agent: 476 #define ND_OPT_PI_FLAG_ROUTER 0x20 /* Router flag in PI */ 478 As per Mobile IPv6 specification [2] a Home Agent MUST include 479 at least one prefix option with the Rouer Address (R) bit set. 480 Advanced Socket API [1] defines data structure for prefix option 481 as follows: 483 struct nd_opt_prefix_info { /* prefix information */ 484 uint8_t nd_opt_pi_type; 485 uint8_t nd_opt_pi_len; 486 uint8_t nd_opt_pi_prefix_len; 487 uint8_t nd_opt_pi_flags_reserved; 488 uint32_t nd_opt_pi_valid_time; 489 uint32_t nd_opt_pi_preferred_time; 490 uint32_t nd_opt_pi_reserved2; 491 struct in6_addr nd_opt_pi_prefix; 492 }; 494 New advertisement interval option and home agent information 495 options are defined in Mobile IPv6 [2] base specification. 497 struct nd_opt_adv_interval { /* Advertisement interval option */ 498 uint8_t nd_opt_ai_type; 499 uint8_t nd_opt_ai_len; 500 uint16_t nd_opt_ai_reserved; 501 uint32_t nd_opt_ai_interval; 502 }; 504 The option types for the new Mobile IPv6 specific options: 506 #define ND_OPT_ADV_INTERVAL 7 /* Adv Interval Option */ 507 #define ND_OPT_HA_INFORMATION 8 /* HA Information option */ 509 struct nd_opt_homeagent_info { /* Home Agent information */ 510 uint8_t nd_opt_hai_type; 511 uint8_t nd_opt_hai_len; 512 uint16_t nd_opt_hai_reserved; 513 uint16_t nd_opt_hai_preference; 514 uint16_t nd_opt_hai_lifetime; 515 }; 517 3. Access to Home Address Destination Option and Routing Headers 519 Applications that need to be able to access home address destination 520 option and routing header type 2 information should use the same 521 mechanism defined in Advanced Sockets API for IPv6 in section 4. 523 In order to receive Home Address destination option or route header 524 type 2 extension header, application must call setsockopt() to turn 525 on the corresponding flag: 527 int on = 1; 529 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); 530 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); 532 When any of these options are enabled, the corresponding data is 533 returned as control information by recvmsg(), as one or more 534 ancillary data objects. Receiving the above information for TCP 535 applications is not defined in this document (see section 4.1 of 536 Advanced Sockets API for IPv6[1]. 538 For sending home address destination option, ancillary data can be 539 used to specify the option content for a single datagram. This 540 only applies to datagram and raw sockets; not to TCP sockets. 541 Advanced API [1] document restricts one IPV6_xxx ancillary data 542 object for a particular extension header in the control buffer. 543 Thus there would be a single ancillary data object for Home address 544 destination option in a ancillary data buffer. If the kernel 545 implementation supports this API, it is responsible for extracting 546 the Home address destination option data object and placing it as 547 destination option extension header in compliance with section 548 6.3 of Mobile IPv6 [2] base specification. 550 For TCP data packets with home-address destination option may be 551 used with "sticky" option for all transmitted packets. However, 552 at this point, it is unknown why an application would want to 553 set home-address option or Route Header Type 2 extension header 554 along with its data packets as Mobile IPv6 protocol takes care of 555 them transparently at the protocol stack. 557 However, the following socket option parameters and cmsghdr fields 558 may be used for sending. 560 opt level/ optname/ optval/ 561 cmsg_level cmsg_type cmsg_data[] 562 ------------ ------------ ------------------------ 563 IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure 564 IPPROTO_IPV6 IPV6_RTHDR ip6_rthdr structure 566 Some IPv6 implementations may support "sticky" options [1] for IPv6 567 destination option for datagram sockets. 569 3.1 Routing Header access functions 571 While accessing Routing header Type 2 extension header, one MUST 572 use type = 2 and segment = 1. The following existing functions 573 defined in Advanced API for IPv6 Sockets [1] are supported 574 for Mobile IPv6 applications for sending and receiving Routing 575 Header Type 2 headers: 577 For sending: 578 size_t inet6_rth_space(int type, int segments); 579 void *inet6_rth_init(void *bp, int bp_len, int type, int segments); 580 int inet6_rth_add(void *bp, const struct in6_addr *addr); 581 For receiving: 582 int inet6_rth_segments(const void *bp); 583 struct in6_addr *inet6_rth_getaddr(const void *bp, int index); 585 NOTE: Reversing operation is not possible using Route Header Type 2 586 extension header. 588 Detail description and examples of accessing a IPv6 Routing Header 589 are discussed in Advanced API for IPv6 Sockets [1]. 590 However, section 7 of Adavanced API for IPv6 Sockets [1] indicates 591 that multiple types of routing headers can be received as multiple 592 ancillary data objects to the application (with cmsg_type set to 593 IPV6_RTHDR). Currently there is no API functions defined to return 594 the routing header type, hence this document defines a function 595 for getting the type of the received routing header. 597 int inet6_rth_gettype(const void *bp); 599 3.2 Home Address Destination Option access functions 601 The application must enable the IPV6_RECVDSTOPTS socket option in 602 order to receive the home address destination option: 604 int on = 1; 605 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); 607 Each Destination option header is returned as one ancillary data 608 object described by a cmsghdr structure with cmsg_level set to 609 IPPROTO_IPV6 and cmsg_type set to IPV6_DSTOPTS. 611 These options are then processed by calling the inet6_opt_next(), 612 inet6_opt_find(), and inet6_opt_get_value() functions as defined 613 in Advanced API for IPv6 sockets [1]. 615 This document assumes that Mobile IPv6 applications will not be 616 allowed to send Home Address Destination Option from the 617 application level, as Mobile IPv6 kernel takes care of sending 618 home-address option and routing header type 2. 620 The Destination options are normally constructed using the 621 inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and 622 inet6_opt_set_val() functions, described in Section 10 of IPv6 623 Advanced API sockets [1]. 625 4. Mobility Protocol Headers 627 Mobile IPv6 [2] defines a new IPv6 protocol header to carry mobility 628 messages between Mobile Nodes, Home Agents and Correspondent Nodes. 629 These protocol headers carry Mobile IPv6 Binding messages as well as 630 Return Routability [2] messages. Currently the specification [2] 631 does not allow transport packets (piggybacking) along with the 632 mobility messages. Thus the mobility protocol header can be 633 accessed through a IPv6 RAW socket. A IPv6 RAW socket that is opened 634 for protocol IPPROTO_MH should always be able to see all the MH 635 (Mobility Header) packets. It is possible that future applications 636 may implement part of Mobile IPv6 signal processing at the 637 application level. Having a RAW socket interface may also enable 638 an application to execute the Return Routability protocol or other 639 future authentication protocol involving mobility header at the user 640 level. 642 4.1 Receiving and Sending Mobility Header Messages 644 This specification recommends IPv6 RAW sockets mechanism to send 645 and receive Mobility Header (MH) packets. The behavior is similar to 646 ICMPV6 processing, where kernel passes a copy of the mobility header 647 packet to the receiving socket. Depending on the implementation 648 kernel may process the mobility header as well in addition to passing 649 the mobility header to the application. 650 In order to comply with the restriction in Advance API for IPv6 [1] 651 sockets, applications should set IPV6_CHECKSUM socket option with 652 IPPROTO_MH protocol RAW Sockets. However, a Mobile IPv6 implementa- 653 tion that supports Mobile IPv6 API, must implement mobility header 654 API checksum calculation by default at the kernel for both incoming 655 and outbound path. A Mobile IPv6 implementation must not return error 656 on IPV6_CHECKSUM socket option setting, even if the socket option is 657 a NO-OP function for that implementation because it verifies the 658 checksum at the kernel level. Mobility Header checksum procedure 659 is described in Mobile IPv6 Protocol [2] specification. 660 Again, it is recommended that the applications set the IPV6_CHECKSUM 661 socket option along with the RAW sockets for IPPROTO_MH protocol, 662 for application portability. 664 As an example, a program that wants to send or receive mobility 665 header protocol(MH), could open a socket as following: 667 fd = socket(AF_INET6, SOCK_RAW, IPPROTO_MH); 669 int offset = 4; 670 setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, 671 sizeof(offset)); 673 For example, if an implementation likes to handle HOTI/HOT and 674 COTI/COT message processing, it can do so by using IPv6 RAW Sockets 675 for IPPROTO_MH at the application layer. 676 The same application may also set IPV6_RECVDSTOPTS socket option for 677 receiving home address option in a binding update [2] from the mobile 678 node. 680 5. Protocols File 682 Many hosts provide the file /etc/protocols that contains the names 683 of the various IP protocols and their protocol numbers. The protocol 684 numbers are obtained through function getprotoXXX() functions. 686 The following addition should be made to the /etc/protocols file, 687 in addition to what is defined in section 2.4 of Advanced Sockets 688 API for IPv6 [1]. 690 The protocol number for Mobility header: 691 (http://www.iana.org/assignments/protocol-numbers) 693 ipv6-mh 135 # Mobility Protocol Header 695 6. IPv4-Mapped IPv6 Addresses 697 The same rule applies as described in section 13 of IPv6 Advanced 698 API for Sockets [1]. Thus processing of IPv4-mapped IPv6 addresses 699 for the Mobile IPv6 specific socket options are out of scope of this 700 document. 702 7. Security Considerations 704 The setting of Home Address Destination option and route header 705 Type 2 IPV6_RTHDR socket option may not be allowed at the 706 application level in order to prevent denial-of-service attacks 707 or man in the middle attacks by hackers. 708 Sending and receiving of mobility header messages are possible by 709 IPv6 RAW sockets. Thus it is assumed that this operation is only 710 possible by priviledged users. However, this API does not prevent 711 the existing security threat from a hacker by sending bogus mobility 712 header or other IPv6 packets using home-address option and Type 2 713 routing extension header. 715 8. References 717 [1] Stevens, W. R, Thomas, M., Nordmark, E., Jinmei, T., "Advanced 718 Sockets API for IPv6", RFC 3542, May 2003 719 April 19, 2002. 721 [2] Johnson, D., Perkins, C., Arkko, J., "Mobility Support in IPv6" 722 draft-ietf-mobileip-ipv6-24.txt, June, 2003. 724 [3] Deering, S., Hinden, R., "Internet Protocol, Version 6 725 (IPv6), Specification", RFC 2460, Dec. 1998. 727 9. Acknowledgement 729 Thanks to Brian Haley for the thorough review of this draft and many 730 helpful comments. Keiichi Shima, Alexandru Petrescu, Ryuji Wakikawa, 731 Vijay Devarapalli, Jim Bound, Suvidh Mathur and other mobile-ip 732 working group members provided valuable input during the API design 733 discussion. Vladislav Yasevich recommended default checksum 734 calculation for mobility header API at the kernel level. 735 Antti Tuominen suggested the routing header type function for this 736 API document. 738 10. Changes from last revision 740 The following changes were made as per feedback from the 741 implementors at Connectathon 2004. 743 * Section 2.1.11.2 now defines alternate COA address data structure 744 as struct in6_addr for consistency. It was defined as 16 unit 745 of bytes. 747 * Added Binding Update Authdata of 12 bytes in the 748 struct ip6_mh_opt_auth_data 750 * Added a new function inet6_rth_gettype() in section 3.1 in order 751 to distinguish routing header type 2 ancillary data items from 752 type 0 routing header ancillary data items on the receive side. 754 * Updated the Acknowledgement and Authors' address section 756 11. Authors' Addresses 758 Samita Chakrabarti 759 Sun Microsystems, Inc. 760 4150 Network Circle, UMPK17-203 761 Santa Clara, CA 95054, USA 762 Email: samita.chakrabarti@Sun.com 764 Erik Nordmark 765 Sun Microsystems Laboratories 766 4150 Network Circle, UMPK17-308 767 Santa Clara, CA 95054, USA 768 Email: Erik.Nordmark@sun.com