idnits 2.17.1 draft-ietf-mip6-mipext-advapi-02.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 3667, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 885. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 896. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 903. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 909. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 877), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 36. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents -- however, there's a paragraph with a matching beginning. Boilerplate error? == 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. ** There are 14 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 488: '... As per Mobile IPv6 specification [2] a Home Agent MUST include...' RFC 2119 keyword, line 583: '...tination option, SHOULD ignore these n...' RFC 2119 keyword, line 589: '...ader Type 2 extension header, one MUST...' RFC 2119 keyword, line 674: '... option SHOULD contain the Care-Of-A...' RFC 2119 keyword, line 681: '...v6 aware applications MUST receive the...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 132 has weird spacing: '...ggested name ...' == Line 183 has weird spacing: '... struct ip6_m...' == Line 195 has weird spacing: '... struct ip6_m...' == Line 196 has weird spacing: '... ip6_mh ip6mh...' == Line 203 has weird spacing: '... struct ip6_...' == (44 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 319, but not defined == Missing Reference: '16' is mentioned on line 393, but not defined == Missing Reference: '0' is mentioned on line 466, but not defined == Unused Reference: '3' is defined on line 814, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 3542 (ref. '1') ** Obsolete normative reference: RFC 3775 (ref. '2') (Obsoleted by RFC 6275) ** Obsolete normative reference: RFC 2460 (ref. '3') (Obsoleted by RFC 8200) Summary: 14 errors (**), 0 flaws (~~), 12 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Samita Chakrabarti 2 Expires: January, 2005 Erik Nordmark 3 Sun Microsystems, Inc. 4 July, 2004 6 Extension to Sockets API for Mobile IPv6 7 9 Status of this Memo 11 By submitting this Internet-Draft, I certify that any applicable 12 patent or other IPR claims of which I am aware have been disclosed, 13 and any of which I become aware will be disclosed, in accordance with 14 RFC 3668. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet- Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet Draft expires January, 2005. 34 Copyright Notice 36 Copyright (C) The Internet Society (2004). All Rights Reserved. 38 Abstract 40 This document describes data structures and API support for Mobile 41 IPv6 as an extension to Advanced Socket API for IPv6. 43 Mobility Support in IPv6 introduces mobility protocol header 44 for IPv6. It is expected that future Mobile IPv6 applications 45 and implementations may need to access Mobility binding messages 46 and Return Routability messages for diagnostic, packet accounting 47 and local policy setting purposes. In order to provide portability 48 for Mobile IP applications that use sockets under IPv6, 49 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 ................................ 13 71 3.1 Routing Header Access Functions ..................... 15 72 3.2 Home Address Destination Option Access Functions .... 16 74 4. Mobility Protocol Headers ............................... 17 76 4.1 Receiving and Sending Mobility Header Messages ....... 18 78 5. Protocols File ........................................... 19 80 6. IPv4-Mapped IPv6 Addresses ............................... 19 82 7. Security Considerations .................................. 19 84 8. IANA Considerations ...................................... 20 86 9. References ............................................... 20 88 10. Acknowledgement ......................................... 20 90 11. Changes from last revisions ............................. 20 92 12. Authors' Addresses ...................................... 21 94 13. Full Copyright Statement ................................ 22 96 1. Introduction 98 Mobility Support in IPv6 [2] defines a new Mobility Protocol header, 99 Home Address destination option and a new Routing Header type. 100 It is expected that Mobile IPv6 user-level implementations and some 101 applications will need to access and process these IPv6 extension 102 headers. This document is an extension to existing Advanced Sockets 103 API document [1]; it addresses the IPv6 Sockets API for Mobile IPv6 104 protocol support. The target applications for this socket API is 105 believed to be the debugging and diagnostic applications as well as 106 some policy applications which would like to receive a copy of 107 protocol information at the application layer. 109 Note that user applications for transferring data between two 110 systems may not need to be mobility aware. Future IPv6 mobility 111 aware applications may use this socket API for per-packet 112 information for further processing at the application layer 113 program interface. 115 This document can be divided into the following parts. 117 1. Definitions of constants and structures for C programs that 118 capture the Mobile IPv6 packet formats on the wire. A common 119 definition of these is useful at least for packet snooping 120 appplications. This is captured in section 2. 122 2. Notes on how to use the IPv6 Advanced API to access Home Address 123 options and type 2 Routing Headers. This is captured in 124 section 3. 126 3. Notes on how user-level applications can observe MH (Mobility 127 Header) packets using raw sockets (in section 4). The IPv6 RAW 128 socket interface described in this document, allows applications 129 to receive MH packets whether or not the systems MH processing 130 takes place in the "kernel" or at the "user space". 132 4. Suggested name for /etc/protocols (in section 5). 134 It is anticipated that Mobile IPv6 will be used widely from mobile 135 devices to Server and Routing platforms. Thus it is useful to have 136 a standard API for portability of Mobile IPv6 applications on a 137 wide variety of platforms and operating systems. 139 The packet information along with access to the extension headers 140 (Routing header and Destination options) are specified using the 141 "ancillary data" fields that were added to the 4.3BSD Reno sockets 142 API in 1990. The reason is that these ancillary data fields are 143 part of the Posix.1g standard and should therefore be adopted by 144 most vendors. This is in conformance with Advanced Sockets API for 145 IPv6 [1]. 147 This document does not address application access to either the 148 authentication header or the encapsulating security payload header. 150 All examples in this document omit error checking in the favor of 151 brevity. 153 We note that many of the functions and socket options defined in this 154 document may have error returns that are not defined in this 155 document. Many of these possible error returns will be recognized 156 only as implementations proceed. 158 Data types in this document follow the Posix.1g format: intN_t means a 159 signed integer of exactly N bits (e.g., int16_t) and uintN_t means an 160 unsigned integer of exactly N bits (e.g., uint32_t). 162 This document provides guidelines on Mobile IPv6 socket applications 163 and believes that some other appropriate standardization body will 164 standardize the APIs along with other IPv6 advanced socket APIs. 166 2. Common Structures and Definitions 168 This API assumes that the fields in the protocol headers are left in 169 the network byte order, which is big-endian for the Internet 170 protocols. If not, then either these constants or the fields being 171 tested must be converted at run-time, using something like htons() or 172 htonl(). 174 A new header file : 176 2.1. The Mobility Header Data Structures 178 2.1.1 The ip6_mh Structure 180 The following structure is defined as a result of including 181 . This is fixed part of the Mobility Header. 183 struct ip6_mh { 184 uint8_t ip6mh_proto; /* NO_NXTHDR by default */ 185 uint8_t ip6mh_hdrlen; /* Header Len in unit of 8 Octets 186 excluding the first 8 Octets */ 187 uint8_t ip6mh_type; /* Type of Mobility Header */ 188 uint8_t ip6mh_reserved; /* Reserved */ 189 uint16_t ip6mh_cksum; /* Mobility Header Checksum */ 190 /* Followed by type specific messages */ 191 }; 193 2.1.2 Binding Refresh Request Mobility Message 195 struct ip6_mh_binding_request { 196 struct ip6_mh ip6mhbr_hdr; 197 uint16_t ip6mhbr_reserved; 198 /* Followed by optional Mobility Options */ 199 }; 201 2.1.3 Home Address Test Init (HoTI) Message 203 struct ip6_mh_home_test_init { 204 struct ip6_mh ip6mhhti_hdr; 205 uint16_t ip6mhhti_reserved; 206 uint32_t ip6mhhti_cookie[2]; /* 64 bit Cookie by MN */ 207 /* Followed by optional Mobility Options */ 208 }; 210 2.1.4 Care-of Address Test Init (CoTI) Message 212 struct ip6_mh_careof_test_init { 213 struct ip6_mh ip6mhcti_hdr; 214 uint16_t ip6mhcti_reserved; 215 uint32_t ip6mhcti_cookie[2]; /* 64 bit Cookie by MN */ 216 /* Followed by optional Mobility Options */ 217 }; 219 2.1.5 Home Address Test (HOT) Message 221 struct ip6_mh_home_test { 222 struct ip6_mh ip6mht_hdr; 223 uint16_t ip6mhht_nonce_index; 224 uint32_t ip6mhht_cookie[2]; /* Cookie from HOTI msg */ 225 uint32_t ip6mhht_keygen[2]; /* 64 Bit Key by CN */ 226 /* Followed by optional Mobility Options */ 227 }; 229 2.1.6 Care Of Address Test (COT) Message 231 struct ip6_mh_careof_test { 232 struct ip6_mh ip6mhct_hdr; 233 uint16_t ip6mhct_nonce_index; 234 uint32_t ip6mhct_cookie[2]; /* Cookie from COTI message */ 235 uint32_t ip6mhct_keygen[2]; /* 64bit key by CN */ 236 /* Followed by optional Mobility Options */ 237 }; 239 2.1.7 Binding Update Mobility Message 241 struct ip6_mh_binding_update { 242 struct ip6_mh ip6mhbu_hdr; 243 uint16_t ip6mhbu_seqno; /* Sequence Number */ 244 uint16_t ip6mhbu_flags; 245 uint16_t ip6mhbu_lifetime; /* Time in unit of 4 sec */ 246 /* Followed by optional Mobility Options */ 247 }; 249 /* Binding Update Flags, in network byte-order */ 250 #define IP6_MH_BU_ACK 0x8000 /* Request a binding ack */ 251 #define IP6_MH_BU_HOME 0x4000 /* Home Registration */ 252 #define IP6_MH_BU_LLOCAL 0x2000 /* Link-local compatibility */ 253 #define IP6_MH_BU_KEYM 0x1000 /* Key management mobility */ 255 2.1.8 Binding Acknowledgment Mobility Message 257 struct ip6_mh_binding_ack { 258 struct ip6_mh ip6mhba_hdr; 259 uint8_t ip6mhba_status; /* Status code */ 260 uint8_t ip6mhba_flags; 261 uint16_t ip6mhba_seqno; 262 uint16_t ip6mhba_lifetime; 263 /* Followed by optional Mobility Options */ 264 }; 266 /* Binding Acknowledgement Flags */ 267 #define IP6_MH_BA_KEYM 0x80 /* Key management mobility */ 269 2.1.9 Binding Error Mobility Message 271 struct ip6_mh_binding_error { 272 struct ip6_mh ip6mhbe_hdr; 273 uint8_t ip6mhbe_status; /* Error Status */ 274 uint8_t ip6mhbe_reserved; 275 struct in6_addr ip6mhbe_homeaddr; 276 /* Followed by optional Mobility Options */ 277 }; 279 2.1.10 Mobility Option TLV data structure 281 struct ip6_mh_opt { 282 uint8_t ip6mhopt_type; /* Option Type */ 283 uint8_t ip6mhopt_len; /* Option Length */ 284 /* Followed by variable length Option Data in bytes */ 285 }; 287 2.1.11 Mobility Option Data Structures 289 2.1.11.1 Binding Refresh Advice 291 struct ip6_mh_opt_refresh_advice { 292 uint8_t ip6mora_type; 293 uint8_t ip6mora_len; 294 uint16_t ip6mora_interval; /* Refresh interval in 4 sec */ 295 }; 297 2.1.11.2 Alternate Care-of Address 299 struct ip6_mh_opt_altcoa { 300 uint8_t ip6moa_type; 301 uint8_t ip6moa_len; 302 struct in6_addr ip6moa_addr; /* Alternate Care-of Address */ 303 }; 305 2.1.11.3 Nonce Indices 307 struct ip6_mh_opt_nonce_index { 308 uint8_t ip6moni_type; 309 uint8_t ip6moni_len; 310 uint16_t ip6moni_home_nonce; 311 uint16_t ip6moni_coa_nonce; 312 }; 314 2.1.11.4 Binding Authorization Data 316 struct ip6_mh_opt_auth_data { 317 uint8_t ip6moad_type; 318 uint8_t ip6moad_len; 319 uint8_t ip6moad_data[12]; 320 }; 322 2.2 Mobility Header Constants 324 IPv6 Next Header Value for Mobility: 325 327 #define IPPROTO_MH 135 /* IPv6 Mobility Header: IANA */ 328 Mobility Header Message Types: 329 331 #define IP6_MH_TYPE_BRR 0 /* Binding Refresh Request */ 332 #define IP6_MH_TYPE_HOTI 1 /* HOTI Message */ 333 #define IP6_MH_TYPE_COTI 2 /* COTI Message */ 334 #define IP6_MH_TYPE_HOT 3 /* HOT Message */ 335 #define IP6_MH_TYPE_COT 4 /* COT Message */ 336 #define IP6_MH_TYPE_BU 5 /* Binding Update */ 337 #define IP6_MH_TYPE_BACK 6 /* Binding ACK */ 338 #define IP6_MH_TYPE_BERROR 7 /* Binding Error */ 340 Mobility Header Message Option Types: 341 343 #define IP6_MHOPT_PAD1 0x00 /* PAD1 */ 344 #define IP6_MHOPT_PADN 0x01 /* PADN */ 345 #define IP6_MHOPT_BREFRESH 0x02 /* Binding Refresh */ 346 #define IP6_MHOPT_ALTCOA 0x03 /* Alternate COA */ 347 #define IP6_MHOPT_NONCEID 0x04 /* Nonce Index */ 348 #define IP6_MHOPT_BAUTH 0x05 /* Binding Auth Data */ 350 Status values accompanied with Mobility Binding Acknowledgement: 351 353 #define IP6_MH_BAS_ACCEPTED 0 /* BU accepted */ 354 #define IP6_MH_BAS_PRFX_DISCOV 1 /* Accepted, but prefix 355 discovery Required */ 356 #define IP6_MH_BAS_UNSPECIFIED 128 /* Reason unspecified */ 357 #define IP6_MH_BAS_PROHIBIT 129 /* Administratively 358 prohibited */ 359 #define IP6_MH_BAS_INSUFFICIENT 130 /* Insufficient 360 resources */ 361 #define IP6_MH_BAS_HA_NOT_SUPPORTED 131 /* HA registration not 362 supported */ 363 #define IP6_MH_BAS_NOT_HOME_SUBNET 132 /* Not Home subnet */ 364 #define IP6_MH_BAS_NOT_HA 133 /* Not HA for this 365 mobile node */ 366 #define IP6_MH_BAS_DAD_FAILED 134 /* DAD failed */ 367 #define IP6_MH_BAS_SEQNO_BAD 135 /* Sequence number out 368 of range */ 370 #define IP6_MH_BAS_HOME_NI_EXPIRED 136 /* Expired Home nonce 371 index */ 372 #define IP6_MH_BAS_COA_NI_EXPIRED 137 /* Expired Care-of 373 nonce index */ 374 #define IP6_MH_BAS_NI_EXPIRED 138 /* Expired Nonce 375 Indices */ 376 #define IP6_MH_BAS_REG_NOT_ALLOWED 139 /* Registration type 377 change disallowed */ 379 Status values for the Binding Error mobility messages: 380 382 #define IP6_MH_BES_UNKNOWN_HAO 1 /* Unknown binding for HOA */ 383 #define IP6_MH_BES_UNKNOWN_MH 2 /* Unknown MH Type */ 385 2.3. IPv6 Home Address Destination Option 387 389 /* Home Address Destination Option */ 390 struct ip6_opt_home_address { 391 uint8_t ip6oha_type; 392 uint8_t ip6oha_len; 393 uint8_t ip6oha_addr[16]; /* Home Address */ 394 }; 396 Option Type Definition: 398 #define IP6OPT_HOME_ADDRESS 0xc9 /* 11 0 01001 */ 400 2.4 Type 2 Routing Header 402 404 /* Type 2 Routing header for Mobile IPv6 */ 405 struct ip6_rthdr2 { 406 uint8_t ip6r2_nxt; /* next header */ 407 uint8_t ip6r2_len; /* length : always 2 */ 408 uint8_t ip6r2_type; /* always 2 */ 409 uint8_t ip6r2_segleft; /* segments left: always 1 */ 410 uint32_t ip6r2_reserved; /* reserved field */ 411 struct in6_addr ip6r2_homeaddr; /* Home Address */ 412 }; 414 2.5 New ICMP Messages for Mobile IPv6 416 ICMP message types and definitions for Mobile IPv6 are defined in 417 419 #define MIP6_HA_DISCOVERY_REQUEST 150 420 #define MIP6_HA_DISCOVERY_REPLY 151 421 #define MIP6_PREFIX_SOLICIT 152 422 #define MIP6_PREFIX_ADVERT 153 424 The following data structures can be used for the ICMP message 425 types discussed in section 6.5 through 6.8 in the base Mobile 426 IPv6 [2] specification. 428 struct mip6_dhaad_req { /* Dynamic HA Address Discovery */ 429 struct icmp6_hdr mip6_dhreq_hdr; 430 }; 432 #define mip6_dhreq_type mip6_dhreq_hdr.icmp6_type 433 #define mip6_dhreq_code mip6_dhreq_hdr.icmp6_code 434 #define mip6_dhreq_cksum mip6_dhreq_hdr.icmp6_cksum 435 #define mip6_dhreq_id mip6_dhreq_hdr.icmp6_data16[0] 436 #define mip6_dhreq_reserved mip6_dhreq_hdr.icmp6_data16[1] 438 struct mip6_dhaad_rep { /* HA Address Discovery Reply */ 439 struct icmp6_hdr mip6_dhrep_hdr; 440 /* Followed by Home Agent IPv6 addresses */ 441 }; 443 #define mip6_dhrep_type mip6_dhrep_hdr.icmp6_type 444 #define mip6_dhrep_code mip6_dhrep_hdr.icmp6_code 445 #define mip6_dhrep_cksum mip6_dhrep_hdr.icmp6_cksum 446 #define mip6_dhrep_id mip6_dhrep_hdr.icmp6_data16[0] 447 #define mip6_dhrep_reserved mip6_dhrep_hdr.icmp6_data16[1] 449 struct mip6_prefix_solicit { /* Mobile Prefix Solicitation */ 450 struct icmp6_hdr mip6_ps_hdr; 451 }; 453 #define mip6_ps_type mip6_ps_hdr.icmp6_type 454 #define mip6_ps_code mip6_ps_hdr.icmp6_code 455 #define mip6_ps_cksum mip6_ps_hdr.icmp6_cksum 456 #define mip6_ps_id mip6_ps_hdr.icmp6_data16[0] 457 #define mip6_ps_reserved mip6_ps_hdr.icmp6_data16[1] 458 struct mip6_prefix_advert { /* Mobile Prefix Adverisements */ 459 struct icmp6_hdr mip6_pa_hdr; 460 /* Followed by one or more PI options */ 461 }; 463 #define mip6_pa_type mip6_pa_hdr.icmp6_type 464 #define mip6_pa_code mip6_pa_hdr.icmp6_code 465 #define mip6_pa_cksum mip6_pa_hdr.icmp6_cksum 466 #define mip6_pa_id mip6_pa_hdr.icmp6_data16[0] 467 #define mip6_pa_flags_reserved mip6_pa_hdr.icmp6_data16[1] 469 #define MIP6_PA_FLAG_MANAGED 0x8000 470 #define MIP6_PA_FLAG_OTHER 0x4000 472 Prefix options are defined in IPv6 Advanced Socket API [1]. 473 Mobile IPv6 Base specification [2] describes the modified 474 behavior in 'Modifications to IPv6 Neighbor Discovery' section. 475 Prefix Options for Mobile IP are defined in the following section. 477 2.6 IPv6 Neighbor Discovery Changes 479 IPv6 Neighbor Discovery changes are also defined in 480 482 New 'Home Agent' flag in router advertisement: 483 #define ND_RA_FLAG_HOMEAGENT 0x20 /* Home Agent flag in RA */ 485 New Router flag with prefix information of the home agent: 486 #define ND_OPT_PI_FLAG_ROUTER 0x20 /* Router flag in PI */ 488 As per Mobile IPv6 specification [2] a Home Agent MUST include 489 at least one prefix option with the Rouer Address (R) bit set. 490 Advanced Socket API [1] defines data structure for prefix option 491 as follows: 493 struct nd_opt_prefix_info { /* prefix information */ 494 uint8_t nd_opt_pi_type; 495 uint8_t nd_opt_pi_len; 496 uint8_t nd_opt_pi_prefix_len; 497 uint8_t nd_opt_pi_flags_reserved; 498 uint32_t nd_opt_pi_valid_time; 499 uint32_t nd_opt_pi_preferred_time; 500 uint32_t nd_opt_pi_reserved2; 501 struct in6_addr nd_opt_pi_prefix; 502 }; 504 New advertisement interval option and home agent information 505 options are defined in Mobile IPv6 [2] base specification. 507 struct nd_opt_adv_interval { /* Advertisement interval option */ 508 uint8_t nd_opt_ai_type; 509 uint8_t nd_opt_ai_len; 510 uint16_t nd_opt_ai_reserved; 511 uint32_t nd_opt_ai_interval; 512 }; 514 The option types for the new Mobile IPv6 specific options: 516 #define ND_OPT_ADV_INTERVAL 7 /* Adv Interval Option */ 517 #define ND_OPT_HA_INFORMATION 8 /* HA Information option */ 519 struct nd_opt_homeagent_info { /* Home Agent information */ 520 uint8_t nd_opt_hai_type; 521 uint8_t nd_opt_hai_len; 522 uint16_t nd_opt_hai_reserved; 523 uint16_t nd_opt_hai_preference; 524 uint16_t nd_opt_hai_lifetime; 525 }; 527 3. Access to Home Address Destination Option and Routing Headers 529 Applications that need to be able to access home address destination 530 option and routing header type 2 information should use the same 531 mechanism defined in Advanced Sockets API for IPv6 in section 4. 533 In order to receive Home Address destination option or Route Header 534 Type 2 extension header, application must call setsockopt() to turn 535 on the corresponding flag: 537 int on = 1; 539 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); 540 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); 542 When any of these options are enabled, the corresponding data is 543 returned as control information by recvmsg(), as one or more 544 ancillary data objects. Receiving the above information for TCP 545 applications is not defined in this document (see section 4.1 of 546 Advanced Sockets API for IPv6 [1]). 548 For sending Home Address destination option, ancillary data can be 549 used to specify the option content for a single datagram. This 550 only applies to datagram and raw sockets; not to TCP sockets. 551 Advanced API [1] document restricts one IPV6_xxx ancillary data 552 object for a particular extension header in the control buffer. 553 Thus there would be a single ancillary data object for Home address 554 destination option in a ancillary data buffer. If the kernel 555 implementation supports this API, it is responsible for extracting 556 the Home address destination option data object and placing it as 557 destination option extension header in compliance with section 558 6.3 of Mobile IPv6 [2] base specification. 560 For TCP data packets with Home Address destination option may be 561 used with "sticky" option for all transmitted packets. However, 562 at this point, it is unknown why an application would want to 563 set Home Address option or Route Header Type 2 extension header 564 along with its data packets as Mobile IPv6 protocol takes care of 565 them transparently at the protocol stack. 567 However, the following socket option parameters and cmsghdr fields 568 may be used for sending. 570 opt level/ optname/ optval/ 571 cmsg_level cmsg_type cmsg_data[] 572 ------------ ------------ ------------------------ 573 IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure 574 IPPROTO_IPV6 IPV6_RTHDR ip6_rthdr structure 576 Some IPv6 implementations may support "sticky" options [1] for IPv6 577 destination option for datagram sockets. 579 Behavior of legacy IPv6 socket applications: 581 Mobile IPv6 un-aware applications or existing IPv6 socket 582 applications that do not know about the new routing header type 2 583 and Home Address destination option, SHOULD ignore these new 584 routing header type and Home Address destination option upon 585 receipt of them. 587 3.1 Routing Header access functions 589 While accessing Routing header Type 2 extension header, one MUST 590 use type = 2 and segment = 1. The following existing functions 591 defined in Advanced API for IPv6 Sockets [1] are supported 592 for Mobile IPv6 applications for sending and receiving Routing 593 Header Type 2 headers: 595 For sending: 597 size_t inet6_rth_space(int type, int segments); 598 void *inet6_rth_init(void *bp, int bp_len, int type, int segments); 599 int inet6_rth_add(void *bp, const struct in6_addr *addr); 601 For receiving: 603 int inet6_rth_segments(const void *bp); 604 struct in6_addr *inet6_rth_getaddr(const void *bp, int index); 606 NOTE: Reversing operation is not possible using Route Header Type 2 607 extension header. 609 Detail description and examples of accessing a IPv6 Routing Header 610 are discussed in Advanced Sockets API for IPv6 [1]. 611 However, section 7 of Adavanced API for IPv6 Sockets [1] indicates 612 that multiple types of routing headers can be received as multiple 613 ancillary data objects to the application (with cmsg_type set to 614 IPV6_RTHDR). Currently there is no API functions defined to return 615 the routing header type, hence this document defines a function 616 for getting the type of the received routing header. 618 int inet6_rth_gettype(const void *bp); 620 3.1.1 Content of Routing Header Type 2 622 It is assumed that no portable applications will send routing hader 623 Type 2 ancillary data from application layer, since many 624 implementations take care of that at the kernel layer and may not 625 support API for sending routing header type 2. However, if any 626 Mobile IPv6 implementation requires to send/process pakcets at the 627 user level, it can use the API mentioned in section 3.1 and set 628 value of routing header as the home-address as specified in [2]. 630 For user level applications that receive routing header type 2, 631 inet6_rth_getaddr() returns the Care-Of-Address or the original 632 destination address of the received packet. This is in compliance 633 with the existing Routing header Type=0 processing for IPv6 [1]. 635 Thus on the receive side, the socket application will always 636 receive data packets at its original home-address. 637 The implementations are responsible for processing the routing 638 header type 2 packet as per Mobile IPv6 RFC [2], before passing 639 the routing header type 2 information to the Socket API. 641 3.2 Home Address Destination Option access functions 643 The application must enable the IPV6_RECVDSTOPTS socket option in 644 order to receive the Home Address destination option: 646 int on = 1; 647 setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); 649 Each Destination option header is returned as one ancillary data 650 object described by a cmsghdr structure with cmsg_level set to 651 IPPROTO_IPV6 and cmsg_type set to IPV6_DSTOPTS. 653 The receive side Home Address destination option is further 654 processed by calling the inet6_opt_next(), inet6_opt_find(), 655 and inet6_opt_get_value() functions as defined in Advanced API 656 for IPv6 sockets [1]. 658 This document assumes that portable Mobile IPv6 applications will 659 not send Home Address Destination Option from the application level, 660 as many Mobile IPv6 implementations take care of sending Home Address 661 option and routing header type 2 at the kernel. However, some 662 embedded software implementations may require to implement the IPv6 663 packet processing/sending at the user level; those implementations 664 may choose to provide API spport for sending home-address option 665 at the application layer. For API which support sending Home Address 666 destination options, they are normally constructed by using the 667 inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and 668 inet6_opt_set_val() functions, described in Section 10 of Advanced 669 sockets API for IPv6 [1]. 671 3.2.1 Content of Home Address Destination option 673 The received ancillary data object for Home Address destination 674 option SHOULD contain the Care-Of-Address of the mobile node. It 675 is assumed that the initial processing of the Home Address 676 destination option will verify the validity of home-address as 677 described in 6.3 and 9.5 of Mobile IPv6 Specification [2] and 678 swap the source address of the packet (COA) with the content of 679 Home Address destination option. 681 All portable Mobile IPv6 aware applications MUST receive the 682 home-address as source address of the incoming packet from the 683 socket-level functions like recvfrom(), recvmsg(), accept() and 684 getpeername(). This is necessary for: 686 - maintaining consistency between simple user-level 687 applications running between mobile nodes and the 688 diagnostic applications on home-agent or on 689 correspondent node, which use this API. 691 - obtaining the COA address of the mobile node when 692 Home Address destination option is used. 694 - maintaining consistency of existing IPv6 Socket APIs 695 and processing of Home Address destination option. 697 If an implementation supports send-side Home Address destination 698 API, then it must follow the same rule for data content as 699 specified in Mobile IPv6 RFC [2] for sending home-address option. 700 Thus the home-address option will contain the home-address and 701 the implementation will use the care-of-address as the source 702 address of the outgoing packet. 704 4. Mobility Protocol Headers 706 Mobile IPv6 [2] defines a new IPv6 protocol header to carry mobility 707 messages between Mobile Nodes, Home Agents and Correspondent Nodes. 708 These protocol headers carry Mobile IPv6 Binding messages as well as 709 Return Routability [2] messages. Currently the specification [2] 710 does not allow transport packets (piggybacking) along with the 711 mobility messages. Thus the mobility protocol header can be 712 accessed through a IPv6 RAW socket. A IPv6 RAW socket that is opened 713 for protocol IPPROTO_MH should always be able to see all the MH 714 (Mobility Header) packets. It is possible that future applications 715 may implement part of Mobile IPv6 signal processing at the 716 application level. Having a RAW socket interface may also enable 717 an application to execute the Return Routability protocol or other 718 future authentication protocol involving mobility header at the user 719 level. 721 4.1 Receiving and Sending Mobility Header Messages 723 This specification recommends IPv6 RAW sockets mechanism to send 724 and receive Mobility Header (MH) packets. The behavior is similar to 725 ICMPV6 processing, where kernel passes a copy of the mobility header 726 packet to the receiving socket. Depending on the implementation 727 kernel may process the mobility header as well in addition to passing 728 the mobility header to the application. 729 In order to comply with the restriction in Advanced Sockets API for 730 IPv6 [1], applications should set IPV6_CHECKSUM socket option with 731 IPPROTO_MH protocol RAW Sockets. A Mobile IPv6 implementation 732 that supports Mobile IPv6 API, must implement Mobility Header 733 API checksum calculation by default at the kernel for both incoming 734 and outbound path. A Mobile IPv6 implementation must not return error 735 on IPV6_CHECKSUM socket option setting, even if the socket option is 736 a NO-OP function for that implementation because it verifies the 737 checksum at the kernel level. Mobility Header checksum procedure 738 is described in Mobile IPv6 Protocol [2] specification. 739 Again, it is recommended that the applications set the IPV6_CHECKSUM 740 socket option along with the RAW sockets for IPPROTO_MH protocol, 741 for application portability. 743 As an example, a program that wants to send or receive mobility 744 header protocol(MH), could open a socket as following: 746 fd = socket(AF_INET6, SOCK_RAW, IPPROTO_MH); 748 int offset = 4; 749 setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, 750 sizeof(offset)); 752 For example, if an implementation likes to handle HOTI/HOT and 753 COTI/COT message processing, it can do so by using IPv6 RAW Sockets 754 for IPPROTO_MH at the application layer. 755 The same application may also set IPV6_RECVDSTOPTS socket option for 756 receiving home-address option in a binding update [2] from the mobile 757 node. 759 5. Protocols File 761 Many hosts provide the file /etc/protocols that contains the names 762 of the various IP protocols and their protocol numbers. The protocol 763 numbers are obtained through function getprotoXXX() functions. 765 The following addition should be made to the /etc/protocols file, 766 in addition to what is defined in section 2.4 of Advanced Sockets 767 API for IPv6 [1]. 769 The protocol number for Mobility Header: 770 (http://www.iana.org/assignments/protocol-numbers) 772 ipv6-mh 135 # Mobility Protocol Header 774 6. IPv4-Mapped IPv6 Addresses 776 The same rule applies as described in section 13 of Advanced Sockets 777 API for IPv6 [1]. Thus processing of IPv4-mapped IPv6 addresses 778 for the Mobile IPv6 specific socket options are out of scope of this 779 document. 781 7. Security Considerations 783 The setting of Home Address Destination option and Route Header 784 Type 2 IPV6_RTHDR socket option may not be allowed at the 785 application level in order to prevent denial-of-service attacks 786 or man in the middle attacks by hackers. 787 Sending and receiving of mobility header messages are possible by 788 IPv6 RAW sockets. Thus it is assumed that this operation is only 789 possible by priviledged users. However, this API does not prevent 790 the existing security threat from a hacker by sending bogus mobility 791 header or other IPv6 packets using Home Address option and Type 2 792 Routing Header extension. 794 8. IANA Considerations 796 This document does not define a new protocol. However, it uses 797 Mobility Header Protocol for IPv6 to define an API for 798 /etc/protocols file. 799 (ref: http://www.iana.org/assignments/protocol-numbers) 801 9. References 803 Normative References: 805 [1] Stevens, W. R, Thomas, M., Nordmark, E., Jinmei, T., "Advanced 806 Sockets API for IPv6", RFC 3542, May 2003 807 April 19, 2002. 809 [2] Johnson, D., Perkins, C., Arkko, J., "Mobility Support in IPv6", 810 RFC3775, June, 2004. 812 Informative References: 814 [3] Deering, S., Hinden, R., "Internet Protocol, Version 6 815 (IPv6), Specification", RFC 2460, Dec. 1998. 817 10. Acknowledgement 819 Thanks to Brian Haley for the thorough review of this draft and many 820 helpful comments. Keiichi Shima, Alexandru Petrescu, Ryuji Wakikawa, 821 Vijay Devarapalli, Jim Bound, Suvidh Mathur, Karen Nielsen, Mark 822 Brost, Vladislav Yasevich and other mobile-ip working group members 823 provided valuable input. Antti Tuominen suggested the routing header 824 type function for this API document. 826 11. Changes from last revisions 828 Version 02 changes: 830 * Added section 3.1.1 and 3.2.1 to clarify content of routing header 831 type 2 and destination options. 833 * Clarified existing socket application behavior in section 3. 835 * Updated introduction to clarify scope of the applications wrt 836 this API 838 * Added IANA section and Full Copyright statement and internet 839 draft boiler plate 841 * Updated acknowledgement section and fixed typo etc. 843 The following changes were made in 01 version per feedback from the 844 implementors at Connectathon 2004. 846 * Section 2.1.11.2 now defines alternate COA address data structure 847 as struct in6_addr for consistency. It was defined as 16 unit 848 of bytes. 850 * Added Binding Update Authdata of 12 bytes in the 851 struct ip6_mh_opt_auth_data 853 * Added a new function inet6_rth_gettype() in section 3.1 in order 854 to distinguish routing header type 2 ancillary data items from 855 type 0 routing header ancillary data items on the receive side. 857 * Updated the Acknowledgement and Authors' address section 859 12. Authors' Addresses 861 Samita Chakrabarti 862 Sun Microsystems, Inc. 863 4150 Network Circle, UMPK17-203 864 Santa Clara, CA 95054, USA 865 Email: samita.chakrabarti@Sun.com 867 Erik Nordmark 868 Sun Microsystems Laboratories 869 4150 Network Circle, UMPK17-308 870 Santa Clara, CA 95054, USA 871 Email: Erik.Nordmark@sun.com 873 13. Full Copyright Statement 875 Copyright (C) The Internet Society (2004). This document is subject 876 to the rights, licenses and restrictions contained in BCP 78, and 877 except as set forth therein, the authors retain all their rights. 879 This document and the information contained herein are provided on an 880 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 881 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 882 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 883 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 884 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 885 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 887 Intellectual Property 889 The IETF takes no position regarding the validity or scope of any 890 Intellectual Property Rights or other rights that might be claimed to 891 pertain to the implementation or use of the technology described in 892 this document or the extent to which any license under such rights 893 might or might not be available; nor does it represent that it has 894 made any independent effort to identify any such rights. Information 895 on the procedures with respect to rights in RFC documents can be 896 found in BCP 78 and BCP 79. 898 Copies of IPR disclosures made to the IETF Secretariat and any 899 assurances of licenses to be made available, or the result of an 900 attempt made to obtain a general license or permission for the use of 901 such proprietary rights by implementers or users of this 902 specification can be obtained from the IETF on-line IPR repository at 903 http://www.ietf.org/ipr. 905 The IETF invites any interested party to bring to its attention any 906 copyrights, patents or patent applications, or other proprietary 907 rights that may cover technology that may be required to implement 908 this standard. Please address the information to the IETF at ietf- 909 ipr@ietf.org. 911 Acknowledgement 913 Funding for the RFC Editor function is currently provided by the 914 Internet Society.