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