idnits 2.17.1 draft-ietf-hip-native-api-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 20. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 768. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 779. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 786. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 792. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document has an RFC 3978 Section 5.2(a) Derivative Works Limitation clause. == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 347 has weird spacing: '... struct soc...' == Line 349 has weird spacing: '... struct add...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 13, 2008) is 5737 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '16' on line 272 == Outdated reference: A later version (-04) exists of draft-ietf-btns-c-api-03 == Outdated reference: A later version (-17) exists of draft-ietf-shim6-multihome-shim-api-05 == Outdated reference: A later version (-12) exists of draft-ietf-shim6-proto-10 ** Obsolete normative reference: RFC 3484 (Obsoleted by RFC 6724) ** Obsolete normative reference: RFC 4423 (Obsoleted by RFC 9063) ** Obsolete normative reference: RFC 4843 (Obsoleted by RFC 7343) ** Obsolete normative reference: RFC 5201 (Obsoleted by RFC 7401) ** Obsolete normative reference: RFC 5205 (Obsoleted by RFC 8005) Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Host Identity Protocol M. Komu 3 Internet-Draft Helsinki Institute for Information 4 Intended status: Experimental Technology 5 Expires: January 14, 2009 Henderson 6 The Boeing Company 7 July 13, 2008 9 Basic Socket Interface Extensions for Host Identity Protocol (HIP) 10 draft-ietf-hip-native-api-05 12 Status of this Memo 14 By submitting this Internet-Draft, each author represents that any 15 applicable patent or other IPR claims of which he or she is aware 16 have been or will be disclosed, and any of which he or she becomes 17 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 This document may not be modified, and derivative works of it may not 19 be created, except to publish it as an RFC and to translate it into 20 languages other than English. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on January 14, 2009. 40 Abstract 42 This document defines extensions to the current sockets API for Host 43 Identity Protocol (HIP). The extensions focus on the use of public- 44 key based identifiers discovered via DNS resolution, but define also 45 interfaces for manual bindings between HITs and locators. With the 46 extensions, the application can also support more relaxed security 47 models where the communication can be non-HIP based, according to 48 local policies. The extensions in document are experimental and 49 provide basic tools for futher experimentation with policies. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. API Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.1. Interaction with the Resolver . . . . . . . . . . . . . . 5 59 3.2. Interaction without a Resolver . . . . . . . . . . . . . . 5 61 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6 62 4.1. Socket Family and Address Structure Extensions . . . . . . 6 63 4.2. Extensions to Resolver Data Structures . . . . . . . . . . 8 64 4.2.1. Resolver Usage . . . . . . . . . . . . . . . . . . . . 9 65 4.3. The Use of getsockname and getpeername Functions . . . . . 10 66 4.4. Validating HITs . . . . . . . . . . . . . . . . . . . . . 10 67 4.5. Source HIT Selection by the System . . . . . . . . . . . . 11 68 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 12 70 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 14 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 76 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 80 10. Normative References . . . . . . . . . . . . . . . . . . . . . 16 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 83 Intellectual Property and Copyright Statements . . . . . . . . . . 18 85 1. Introduction 87 This document defines C-based sockets Application Programming 88 Interface (API) extensions for handling HIP-based identifiers 89 explicitly in HIP-aware applications. It is up to the applications, 90 or high-level programming languages or libraries, to manage the 91 identifiers. The extensions in this document are mainly related to 92 the use case in which a DNS resolution step has occurred prior to the 93 creation of a new socket, and assumes that the system has cached or 94 is otherwise able to resolve identifiers to locators (IP addresses). 95 The DNS extensions for HIP are described in [RFC5205]. The 96 extensions also cover the case in which an application may want to 97 explicitly provide suggested locators with the identifiers, including 98 supporting the opportunistic case in which the system does not know 99 the peer host identity. 101 The Host Identity Protocol (HIP) [RFC4423] proposes a new 102 cryptographic namespace by separating the roles of end-point 103 identifiers and locators by introducing a new namespace to the TCP/IP 104 stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on 105 identity-locator split. Note that the APIs specified in this 106 document are specific to HIP. However, the APIs here have been 107 designed as much as possible so as not to preclude its use with other 108 protocols. The use of these APIs with other protocols is, 109 nevertheless, for further study. 111 Applications can observe the HIP layer and its identifiers in the 112 networking stacks with varying degrees of visibility. 113 [I-D.ietf-hip-applications] discusses the lowest levels of visibility 114 in which applications are completely unaware of the underlying HIP 115 layer. Such HIP-unaware applications in some circumstances use HIP- 116 based identifiers, such as LSIs or HITs, instead of IPv4 or IPv6 117 addresses and cannot observe the identifier-locator bindings. 119 This document specifies extensions to [RFC3493] to define a new 120 socket address family, AF_HIP. The macro AF_HIP is used as an alias 121 for PF_HIP in this document because the distinction between AF and PF 122 has been lost in practice. The extensions also describe a new socket 123 address structure for sockets using Host Identity Tags (HITs) 124 explicitly and describe how the socket calls in [RFC3493] are adapted 125 or extended as a result. 127 Some applications may accept incoming communications from any 128 identifier. Other applications may initiate outgoing communications 129 without the knowledge of the peer identifier in Opportunistic Mode 130 [RFC5201] by just relying on a peer locator. This document describes 131 how to address both situations using "wildcards" as described later 132 in this document. 134 There are two related API documents. Multihoming and explicit 135 locator-handling related APIs are defined in 136 [I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes 137 and channel bindings APIs are defined in [I-D.ietf-btns-c-api]. Most 138 of the extensions defined in this document can be used independently 139 of the two mentioned related API documents. 141 The identity-locator split introduced by HIP introduces some policy 142 related challenges with datagram oriented sockets, opportunistic 143 mode, and manual bindings between HITs and locators. The extensions 144 in this document are of experimental nature and provide basic tools 145 for experimenting with policies. Policy related issues are left for 146 further experimentation. 148 To recap, the extensions in this document have three goals. The 149 first goal is to allow HIP-aware applications to open sockets to 150 other hosts based on the HITs alone, presuming that the underlying 151 system can resolve the HITs to addresses used for initial contact. 152 The second goal is that applications can explicitly initiate 153 communications with unknown peer identifiers. The third goal is to 154 define how HIP-aware applications may provide suggested initial 155 contact addresses along with the HITs. 157 2. Terminology 159 The terms used in this document are summarized in Table 1. 161 +---------+---------------------------------------------------------+ 162 | Term | Explanation | 163 +---------+---------------------------------------------------------+ 164 | HIP | Host Identity Protocol | 165 | HIT | Host Identity Tag, a 100-bit hash of a public key with | 166 | | a 28 bit prefix | 167 | LSI | Local Scope Identifier, a local, 32-bit descriptor for | 168 | | a given public key. | 169 | Locator | Routable IPv4 or IPv6 address used at the lower layers | 170 +---------+---------------------------------------------------------+ 172 Table 1 174 3. API Overview 176 This section provides an overview of how the API can be used. First, 177 the case in which a resolver is involved in name resolution is 178 described, and then the case in which no resolver is involved is 179 described. 181 3.1. Interaction with the Resolver 183 Before an application can establish network communications with the 184 entity named by a given FQDN or relative host name, the application 185 must translate the name into the corresponding identifier(s). DNS- 186 based hostname-to-identifier translation is illustrated in Figure 1. 187 The application calls the resolver in step a to resolve an FQDN step 188 b. The DNS server responds with a list of HITs and a set of locators 189 step c. Optionally in step d, the resolver caches the HIT to locator 190 mapping to the HIP module. The resolver returns the HITs to the 191 application step e. Finally, the application selects one HIT and 192 uses it in a socket call such as connect() in step f. 194 +----------+ 195 | | 196 | DNS | 197 | | 198 +----------+ 199 ^ | 200 b. | | c. 202 +-------------+ a. getaddrinfo() +----------+ 203 | |------------------------>| | 204 | Application | | Resolver | 205 | |<------------------------| | 206 +-------------+ e. +----------+ 207 | | 208 | | 209 | f. connect() | d. 210 v v 211 +----------+ +----------+ 212 | | | | 213 | TCP/IP | | HIP | 214 | Stack | | | 215 +----------+ +----------+ 217 Figure 1 219 In practice, the resolver functionality can be implemented in 220 different ways. For example, it may be implemented in existing 221 resolver libraries or as a DNS proxy. 223 3.2. Interaction without a Resolver 225 The extensions in this document focus on the use of the resolver to 226 map host names to HITs and locators in HIP-aware applications. The 227 resolver associates implicitly the HIT with the locator(s) by e.g. 228 communicating the HIT-to-IP mapping to the HIP daemon. However, it 229 is possible that an application operates directly on a peer HIT 230 without interacting with the resolver. In such a case, the 231 application may resort to the system to map the peer HIT to an IP 232 address. Alternatively, the application can explicitly map the HIT 233 to an IP address using socket options as specified in 234 [I-D.ietf-shim6-multihome-shim-api]. Full support for all of the 235 extensions defined in this draft requires shim socket options to be 236 implemented by the system. 238 4. API Syntax and Semantics 240 In this section, we describe the native HIP APIs using the syntax of 241 the C programming language. We limit the description to the 242 interfaces and data structures that are either modified or completely 243 new, because the native HIP APIs are otherwise identical to the 244 sockets API [POSIX]. 246 4.1. Socket Family and Address Structure Extensions 248 The sockets API extensions define a new protocol family, PF_HIP, and 249 a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to 250 each other. These definition shall be defined as a result of 251 including . 253 The use of the PF_HIP constant is mandatory with the socket() 254 function when an application uses the native HIP APIs. The 255 application gives the PF_HIP constant as the first argument (domain) 256 to the socket() function. The system returns a positive integer 257 representing a socket descriptor when the system supports HIP. 258 Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT. 260 Figure 2 shows socket address structure for HIP. 262 #include 264 typedef struct in6_addr hip_hit_t; 266 struct sockaddr_hip { 267 sa_family_t ship_family; 268 in_port_t ship_port; 269 uint32_t ship_pad; 270 uint64_t ship_flags; 271 hip_hit_t ship_hit; 272 uint8_t ship_reserved[16]; 273 }; 275 Figure 2 277 Figure 2 is in in 4.3BSD format. The family of the socket, 278 ship_family, is set to AF_HIP. The port number ship_port is two 279 octets in network byte order. and the ship_hit is 16 octets in 280 network byte order. An implementation may have extra member(s) in 281 this structure. 283 The application usually sets the ship_hit field using the resolver. 284 However, the application can use three special wildcard macros to set 285 a value directly into the ship_hit field. The macros are 286 HIP_HIT_ANY, HIP_HIT_ANY_PUB, HIP_HIT_ANY_TMP and HIP_ADDR_ANY. The 287 first three equal to a HIT value associated with a wildcard HIT of 288 any, public, or anonymous type. The fourth macro, HIP_ADDR_ANY, 289 denotes both HIP_HIT_ANY or any IPv4 or IPv6 address. The 290 HIP_HIT_ANY equals to HIP_HIT_ANY_PUB or HIP_HIT_ANY_TMP. The 291 anonymous identifiers refer to the use anonymous identifiers as 292 specified in [RFC4423]. The system may designate anonymous 293 identifiers as meta data associated with a HIT depending on whether 294 it has been published or not. However, there is no difference in the 295 classes of HITs from the HIP protocol perspective, 297 The application can use the HIP_HIT_ANY_* and HIP_ADDR_ANY macros to 298 accept incoming communications to all of the HITs of the local host. 299 Incoming communications refers here to the functions such as bind(), 300 recvfrom() and recvmsg(). The HIP_HIT_* macros are similar to the 301 sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are 302 applicable to HITs only. After initial contact with the peer, the 303 application can discover the local and peer HITs using getsockname() 304 and getpeername() calls in the context of connection oriented 305 sockets. The difference between the use of the HIP_HIT_* and 306 HIP_ADDR_ANY macros here is that the former allows only HIP-based 307 communications but the latter also allows communications without HIP. 309 The application also uses the HIP_HIT_ANY macro in ship_hit field to 310 establish outgoing communications in Opportunistic mode [RFC5201], 311 i.e., when the application knows the remote peer locator but not the 312 HIT. Outgoing communications refers here to the use of functions 313 such as connect(), sendto() and sendmsg(). However, the application 314 must first associate the socket with at least one IP address of the 315 peer using SHIM_LOCLIST_PEER_PREF socket option. 317 The use of HIP_ADDR_ANY macro in the context of outgoing 318 communications is left for further experimentation. It could be used 319 for establishing a non-HIP based connectivity when HIP-based 320 connectivity was unsuccessful. 322 Some applications rely on system level access control, either 323 implicit or explicit (such as accept_filter() function found on BSD- 324 based systems), but such discussion is out of scope. Other 325 applications implement access control themselves by using the HITs. 326 In such a case, the application can compare two HITs using memcmp() 327 or similar function. It should be noticed that different connection 328 attempts between the same two hosts can result in different HITs 329 because a host is allowed to have multiple HITs. 331 4.2. Extensions to Resolver Data Structures 333 The HIP APIs introduce a new addrinfo flag, HIP_PREFER_ORCHID, to be 334 used by application to query for both HIT and locator information via 335 the getaddrinfo() resolver function [RFC3493]. The getaddrinfo() 336 function uses a data structure used for both input to and output from 337 the resolver. The data structure is illustrated in Figure 3. 339 #include 341 struct addrinfo { 342 int ai_flags; /* e.g. AI_EXTFLAGS */ 343 int ai_family; /* e.g. AF_HIP */ 344 int ai_socktype; /* e.g. SOCK_STREAM */ 345 int ai_protocol; /* 0 or IPPROTO_HIP */ 346 socklen_t ai_addrlen; /* size of *ai_addr */ 347 struct sockaddr *ai_addr; /* sockaddr_hip */ 348 char *ai_canonname; /* canon. name of the host */ 349 struct addrinfo *ai_next; /* next endpoint */ 350 int ai_eflags; /* RFC5014 extension */ 351 }; 353 Figure 3 355 Application must set both the flag AI_EXTFLAGS [RFC5014] in ai_flags 356 and HIP_PREFER_ORCHID in the ai_eflags, or otherwise the resolver 357 does not return sockaddr_hip data structures. The resolver returns 358 EAI_BADFLAGS when it does not support HIP_PREFER_ORCHID or 359 AI_EXTFLAGS flags. 361 Application denotes its preference for public and anonymous types of 362 HITs using HIP_PREFER_SRC_PUBLIC and HIP_PREFER_SRC_TMP flags in the 363 ai_eflags field. If the application sets neither of the flags, the 364 resolver returns both public and anonymous HITs. 366 The simultaneous use of both HIP_PREFER_ORCHID and 367 HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip structure 368 containing a wildcard address that the application can use either for 369 incoming (node argument is NULL in getaddrinfo) or outgoing 370 communications (node argument is non-NULL). For example, 371 HIP_PREFER_PASSIVE_HIT_TMP flag produces one sockaddr_hip structure 372 that contains a HIP_HIT_ANY_TMP in the ship_hit field. 374 The resolver sets the ai_family field to AF_HIP in the addrinfo 375 structure when ai_addr points to a sockaddr_hip structure. 377 When ai_protocol field is set to zero, the resolver also returns 378 locators in sockaddr_in and sockaddr_in6 structures in addition to 379 sockaddr_hip structures. The resolver returns only sockaddr_hip 380 structures when the application has set the ai_protocol field to 381 IPPROTO_HIP or a sockaddr_hip structure is given as the hint argument 382 to the resolver. 384 4.2.1. Resolver Usage 386 A HIP-aware application creates the sockaddr_hip structures 387 explicitly or obtains them from the resolver. The explicit 388 configuration of locators is described in 389 [I-D.ietf-shim6-multihome-shim-api]. This document defines 390 "automated" resolver extensions for getaddrinfo() resolver [RFC3493]. 392 #include 394 int getaddrinfo(const char *nodename, 395 const char *servname, 396 const struct addrinfo *hints, 397 struct addrinfo **res) 398 void free_addrinfo(struct addrinfo *res) 400 Figure 4 402 As described in [RFC3493], the getaddrinfo function takes the 403 nodename, servname, and hints as its input arguments. It places the 404 result of the query into the res argument. The return value is zero 405 on success, or a non-zero error value on error. The nodename 406 argument specifies the host name to be resolved; a NULL argument 407 denotes the local host. The servname parameter declares the port 408 number to be set in the socket addresses in the res output argument. 409 Both the nodename and servname cannot be NULL. 411 The input argument "hints" acts like a filter that defines the 412 attributes required from the resolved endpoints. A NULL hints 413 argument indicates that any kind of endpoints are acceptable. 415 The output argument "res" is dynamically allocated by the resolver. 416 The application frees res argument with the free_addrinfo function. 417 The res argument contains a linked list of the resolved endpoints. 418 The linked list contains sockaddr_hip structures only when the input 419 argument has the HIP_PREFER_ORCHID flag set in ai_eflags. The 420 resolver inserts HITs before any locators. When the 421 HIP_PREFER_ORCHID flag is set, the resolver does not return LSIs or 422 HITs encapsulated into sockaddr_in or sockaddr_in6 data structures as 423 described in [I-D.ietf-hip-applications]. 425 Resolver can return a HIT which maps to multiple locators. The 426 resolver may cache the locator mappings to the HIP module. The HIP 427 module manages the multiple locators according to system policies of 428 the host. The multihoming document 429 [I-D.ietf-shim6-multihome-shim-api] describes how an application can 430 override system default policies. 432 It should be noticed that the application can configure the HIT 433 explicitly without setting the locator or the resolver can fail to 434 resolve any locator. In this scenario, the application relies on the 435 system to map the HIT to an IP address. When the system fails to 436 provide the mapping, it returns -1 in the called sockets API function 437 to the application and sets errno to EADDRNOTAVAIL. 439 4.3. The Use of getsockname and getpeername Functions 441 The application usually discovers the local or peer HITs from the 442 sockaddr_hip structures returned by getaddrinfo(). However, the 443 sockaddr_hip structure does not contain a HIT when the application 444 uses the HIP_HIT_ANY_* macros. In such a case, the application 445 discovers the local and peer HITs using the getsockname() and 446 getpeername() functions. The functions return sockaddr_hip 447 structures when the family of the socket is AF_HIP. 449 4.4. Validating HITs 451 An application that uses the HIP_ADDR_ANY macro may want to check if 452 the local or peer address is an orchid-based HIT [RFC4843]. Also, 453 the application may want to verify whether a HIT is public or 454 anonymous. The application accomplishes these using a new function 455 called sockaddr_is_srcaddr() which is illustrated in Figure 5. 457 #include 459 short sockaddr_is_srcaddr(struct sockaddr *srcaddr 460 uint64_t flags); 462 Figure 5 464 The sockaddr_is_srcaddr() function operates in the same way as 465 inet6_is_srcaddr() function [RFC5014] which can be used to verify the 466 type of an address belonging to the localhost. The difference is 467 that sockaddr_is_srcaddr() function handles sockaddr_hip structures 468 in addition to sockaddr_in6, and possibly some other socket 469 structures in further extensions. The function has also 64 bit flags 470 instead of 32 bits. This new function handles the same flags as 471 defined in [RFC5014] in addition to some HIP-specific flags listed in 472 Table 2. 474 +-----------------------+-------------------------+ 475 | Flag | Purpose | 476 +-----------------------+-------------------------+ 477 | HIP_PREFER_ORCHID | The identifier is a HIT | 478 | HIP_PREFER_SRC_TMP | Anonymous HIT | 479 | HIP_PREFER_SRC_PUBLIC | Public HIT | 480 +-----------------------+-------------------------+ 482 Table 2 484 4.5. Source HIT Selection by the System 486 Some applications initiate communications by specifying only the 487 destination identifier and let the underlying system specify the 488 source. When the system selects the source HIT, the system should 489 apply the rules specified in [RFC3484] according to the default 490 policy table for HITs shown in Table 3. 492 +-----------------+------------+-------+ 493 | HIT Type | Precedence | Label | 494 +-----------------+------------+-------+ 495 | Anonymous DSA | 110 | 5 | 496 | Anonymous RSA | 120 | 6 | 497 | Public DSA | 130 | 7 | 498 | Public RSA | 140 | 8 | 499 | [RFC3484] rules | 50-100 | 7 | 500 +-----------------+------------+-------+ 502 Table 3 504 When application using a AF_HIP-based socket does not specify the 505 source identifier, the system selects the source identifier on the 506 behalf of the application according to the precedence in the above 507 table. For example, the system prefers public (published) keys 508 before anonymous keys because they work better for referral purposes. 509 RSA-based keys are preferred over DSA based because RSA is the 510 default algorithm in HIP. 512 When system provides multiple keys of same type, but with different 513 key lengths, the longer keys should have a higher preference. As 514 example, system providing two public RSA keys of different size would 515 give the smaller key preference value 140 and 145 for the larger. 516 The preference value should not exceed 150. Systems supporting more 517 than 10 keys of same key size may use digits to further fragment the 518 precedence namespace. IPv6 addresses have the lowest precedence 519 value to denote that HITs have a higher precedence when operating on 520 AF_HIP-based sockets. 522 [RFC5014] specifies flags for the getaddrinfo resolver and socket 523 options for Mobile IPv6. The resolver, operating under 524 HIP_PREFER_ORCHID flag, or the socket handler, operating on a AF_HIP- 525 based socket, may encounter such flags or options. In such a case 526 the resolver or socket handler should silenty ignore the flags or 527 options without returning an error. However, a HIP-aware application 528 may use the HIP-specific flags HIP_PREFER_ORCHID, HIP_PREFER_SRC_TMP 529 or HIP_PREFER_SRC_PUBLIC in getsockopt(), setsockopt(), getaddrinfo() 530 calls and in the anchillary data of datagram packets as specified in 531 [RFC5014]. The level of the socket options should be set to SOL_SHIM 532 [I-D.ietf-shim6-multihome-shim-api] and the option name should be 533 HIP_HIT_PREFERENCES. 535 4.6. Explicit Handling of Locators 537 The system resolver, or the HIP module, maps HITs to locators 538 implicitly. However, some applications may want to specify initial 539 locator mappings explicitly. In such a case, the application first 540 creates a socket with AF_HIP as the domain argument. Second, the 541 application may set locator information with one of the following 542 shim socket options as defined in the multihoming extensions in 543 [I-D.ietf-shim6-multihome-shim-api]: 545 +-----------------------------+-----+-----+-----------------+-------+ 546 | optname | get | set | description | dtype | 547 +-----------------------------+-----+-----+-----------------+-------+ 548 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 549 | | | | preferred | | 550 | | | | locator on the | | 551 | | | | local side for | | 552 | | | | the context | | 553 | | | | associated with | | 554 | | | | the socket. | | 555 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 556 | | | | preferred | | 557 | | | | locator on the | | 558 | | | | remote side for | | 559 | | | | the context | | 560 | | | | associated with | | 561 | | | | the socket. | | 562 | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *2 | 563 | | | | list of | | 564 | | | | locators | | 565 | | | | associated with | | 566 | | | | the local EID. | | 567 | SHIM_LOCLIST_PEER | o | o | Get or set a | *2 | 568 | | | | list of | | 569 | | | | locators | | 570 | | | | associated with | | 571 | | | | the peer's EID. | | 572 | SHIM_LOC_LOCAL_SEND | o | o | Request use of | *2 | 573 | | | | specific | | 574 | | | | locator as | | 575 | | | | source locator | | 576 | | | | of outgoing IP | | 577 | | | | packets. | | 578 | SHIM_LOC_PEER_SEND | o | o | Request use of | *2 | 579 | | | | specific | | 580 | | | | locator as | | 581 | | | | destination | | 582 | | | | locator of | | 583 | | | | outgoing IP | | 584 | | | | packets. | | 585 +-----------------------------+-----+-----+-----------------+-------+ 586 *1: Pointer to a shim_locator which is defined in Section 7 of 587 draft-ietf-shim6-multihome-shim-api. 588 *2: Pointer to an array of shim_locator. 590 Figure 6 592 Finally, the application creates a valid sockaddr_hip structure and 593 associates the socket also with the sockaddr_hip structure by calling 594 some socket-related function, such as connect() or bind(). 596 The usage and semantics for typical use cases are as follows: 598 An application that initiates a connection using a connection 599 oriented socket to a particular host at a known address or set of 600 addresses can invoke SHIM_LOCLIST_PEER socket option. The HIP module 601 uses the first address (if multiple are provided, or else the 602 application can override this by setting SHIM_LOC_PEER_PREF to one of 603 the addresses in SHIM_LOCLIST_PEER. The application later provides a 604 specific HIT in the ship_hit field of the sockaddr_hip in the 605 connect() system call. If the application provides one or more 606 addresses in SHIM_LOCLIST_PEER setsockopt call, the system should not 607 connect to the host via another destination address, in case the 608 application intends to restrict the range of addresses permissible as 609 a policy choice. If the system cannot reach the provided HIT at one 610 of the addresses provided, the outbound socket API functions 611 (connect, sendmsg, etc.) return -1 and set errno to EINVALIDLOCATOR. 613 Another common use case is to set up an association in opportunistic 614 mode, when the destination HIT is specified as a wildcard. This can 615 be accomplished by setting one or more destination addresses using 616 the SHIM_LOCLIST_PEER socket option as described above and then 617 calling connect() with the wildcard HIT. The connect() call returns 618 -1 and sets errno to EADDRNOTAVAIL when the application connects to a 619 wildcard without specifying any destination address. 621 Applications may also choose to associate local addresses with 622 sockets. The procedures specified in 623 [I-D.ietf-shim6-multihome-shim-api] are followed in this case. 625 5. Summary of New Definitions 627 Table 4 summarizes the new macro and structures defined in this 628 document. 630 +-----------------+-----------------------------+ 631 | Header | Definition | 632 +-----------------+-----------------------------+ 633 | | AF_HIP | 634 | | PF_HIP | 635 | | IPPROTO_HIP | 636 | | HIP_HIT_ANY | 637 | | HIP_HIT_ANY_PUB | 638 | | HIP_HIT_ANY_TMP | 639 | | HIP_ADDR_ANY | 640 | | HIP_HIT_PREFERENCES | 641 | | hip_hit_t | 642 | | HIP_PREFER_ORCHID | 643 | | HIP_PREFER_SRC_TMP | 644 | | HIP_PREFER_SRC_PUBLIC | 645 | | HIP_PREFER_PASSIVE_HIT_TMP | 646 | | HIP_PREFER_PASSIVE_HIT_PUB | 647 | | HIP_PREFER_PASSIVE_HIT_ANY | 648 | | HIP_PREFER_PASSIVE_ADDR_ANY | 649 | | sockaddr_hip | 650 | | sockaddr_is_srcaddr | 651 +-----------------+-----------------------------+ 653 Table 4 655 6. IANA Considerations 657 No IANA considerations. 659 7. Security Considerations 661 No security considerations currently. 663 8. Contributors 665 Thanks for Jukka Ylitalo and Pekka Nikander for their original 666 contribution, time and effort to the native HIP APIs. Thanks for 667 Yoshifuji Hideaki for his contributions to this document. 669 9. Acknowledgements 671 Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan 672 Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti 673 Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen, 674 Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and 675 Gonzalo Camarillo have also provided valuable ideas or feedback. 676 Thanks also for the APPS area folks, including Stephane Bortzmeyer, 677 Chris Newman, Tony Finch, "der Mouse" and Keith Moore. 679 10. Normative References 681 [I-D.ietf-btns-c-api] 682 Richardson, M., Williams, N., Komu, M., and S. Tarkoma, 683 "IPsec Application Programming Interfaces", 684 draft-ietf-btns-c-api-03 (work in progress), 685 February 2008. 687 [I-D.ietf-hip-applications] 688 Henderson, T., Nikander, P., and M. Komu, "Using the Host 689 Identity Protocol with Legacy Applications", 690 draft-ietf-hip-applications-04 (work in progress), 691 July 2008. 693 [I-D.ietf-shim6-multihome-shim-api] 694 Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, 695 "Socket Application Program Interface (API) for 696 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-05 697 (work in progress), February 2008. 699 [I-D.ietf-shim6-proto] 700 Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 701 Shim Protocol for IPv6", draft-ietf-shim6-proto-10 (work 702 in progress), February 2008. 704 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 705 Std. 1003.1-2001 Standard for Information Technology - 706 Portable Operating System Interface (POSIX)", Dec 2001. 708 [RFC3484] Draves, R., "Default Address Selection for Internet 709 Protocol version 6 (IPv6)", RFC 3484, February 2003. 711 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 712 Stevens, "Basic Socket Interface Extensions for IPv6", 713 RFC 3493, February 2003. 715 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 716 (HIP) Architecture", RFC 4423, May 2006. 718 [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix 719 for Overlay Routable Cryptographic Hash Identifiers 720 (ORCHID)", RFC 4843, April 2007. 722 [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 723 Socket API for Source Address Selection", RFC 5014, 724 September 2007. 726 [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, 727 "Host Identity Protocol", RFC 5201, April 2008. 729 [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol 730 (HIP) Domain Name System (DNS) Extensions", RFC 5205, 731 April 2008. 733 Authors' Addresses 735 Miika Komu 736 Helsinki Institute for Information Technology 737 Metsaenneidonkuja 4 738 Helsinki 739 Finland 741 Phone: +358503841531 742 Fax: +35896949768 743 Email: miika@iki.fi 744 URI: http://www.iki.fi/miika/ 746 Thomas Henderson 747 The Boeing Company 748 P.O. Box 3707 749 Seattle, WA 750 USA 752 Email: thomas.r.henderson@boeing.com 754 Full Copyright Statement 756 Copyright (C) The IETF Trust (2008). 758 This document is subject to the rights, licenses and restrictions 759 contained in BCP 78, and except as set forth therein, the authors 760 retain all their rights. 762 This document and the information contained herein are provided on an 763 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 764 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 765 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 766 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 767 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 768 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 770 Intellectual Property 772 The IETF takes no position regarding the validity or scope of any 773 Intellectual Property Rights or other rights that might be claimed to 774 pertain to the implementation or use of the technology described in 775 this document or the extent to which any license under such rights 776 might or might not be available; nor does it represent that it has 777 made any independent effort to identify any such rights. Information 778 on the procedures with respect to rights in RFC documents can be 779 found in BCP 78 and BCP 79. 781 Copies of IPR disclosures made to the IETF Secretariat and any 782 assurances of licenses to be made available, or the result of an 783 attempt made to obtain a general license or permission for the use of 784 such proprietary rights by implementers or users of this 785 specification can be obtained from the IETF on-line IPR repository at 786 http://www.ietf.org/ipr. 788 The IETF invites any interested party to bring to its attention any 789 copyrights, patents or patent applications, or other proprietary 790 rights that may cover technology that may be required to implement 791 this standard. Please address the information to the IETF at 792 ietf-ipr@ietf.org.