idnits 2.17.1 draft-ietf-hip-native-api-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) == The document has an IETF Trust Provisions of 28 Dec 2009, Section 6.c(i) Publication Limitation clause. 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 copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 357 has weird spacing: '... struct soc...' == Line 359 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 (May 22, 2009) is 5447 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 280 == Outdated reference: A later version (-17) exists of draft-ietf-shim6-multihome-shim-api-08 ** 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 (~~), 5 warnings (==), 4 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: November 23, 2009 Henderson 6 The Boeing Company 7 May 22, 2009 9 Basic Socket Interface Extensions for Host Identity Protocol (HIP) 10 draft-ietf-hip-native-api-06 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. This document may not be modified, 16 and derivative works of it may not be created, except to format it 17 for publication as an RFC or to translate it into languages other 18 than English. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on November 23, 2009. 38 Copyright Notice 40 Copyright (c) 2009 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents in effect on the date of 45 publication of this document (http://trustee.ietf.org/license-info). 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. 49 Abstract 51 This document defines extensions to the current sockets API for Host 52 Identity Protocol (HIP). The extensions focus on the use of public- 53 key based identifiers discovered via DNS resolution, but define also 54 interfaces for manual bindings between HITs and locators. With the 55 extensions, the application can also support more relaxed security 56 models where the communication can be non-HIP based, according to 57 local policies. The extensions in document are experimental and 58 provide basic tools for futher experimentation with policies. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. API Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3.1. Interaction with the Resolver . . . . . . . . . . . . . . 5 68 3.2. Interaction without a Resolver . . . . . . . . . . . . . . 5 70 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6 71 4.1. Socket Family and Address Structure Extensions . . . . . . 6 72 4.2. Extensions to Resolver Data Structures . . . . . . . . . . 8 73 4.2.1. Resolver Usage . . . . . . . . . . . . . . . . . . . . 9 74 4.3. The Use of getsockname and getpeername Functions . . . . . 10 75 4.4. Validating HITs . . . . . . . . . . . . . . . . . . . . . 10 76 4.5. Source HIT Selection by the System . . . . . . . . . . . . 11 77 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 12 79 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 14 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 85 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 89 10. Normative References . . . . . . . . . . . . . . . . . . . . . 16 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 93 1. Introduction 95 This document defines C-based sockets Application Programming 96 Interface (API) extensions for handling HIP-based identifiers 97 explicitly in HIP-aware applications. It is up to the applications, 98 or high-level programming languages or libraries, to manage the 99 identifiers. The extensions in this document are mainly related to 100 the use case in which a DNS resolution step has occurred prior to the 101 creation of a new socket, and assumes that the system has cached or 102 is otherwise able to resolve identifiers to locators (IP addresses). 103 The DNS extensions for HIP are described in [RFC5205]. The 104 extensions also cover the case in which an application may want to 105 explicitly provide suggested locators with the identifiers, including 106 supporting the opportunistic case in which the system does not know 107 the peer host identity. 109 The Host Identity Protocol (HIP) [RFC4423] proposes a new 110 cryptographic namespace by separating the roles of end-point 111 identifiers and locators by introducing a new namespace to the TCP/IP 112 stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on 113 identity-locator split. Note that the APIs specified in this 114 document are specific to HIP. However, the APIs here have been 115 designed as much as possible so as not to preclude its use with other 116 protocols. The use of these APIs with other protocols is, 117 nevertheless, for further study. 119 Applications can observe the HIP layer and its identifiers in the 120 networking stacks with varying degrees of visibility. [RFC5338] 121 discusses the lowest levels of visibility in which applications are 122 completely unaware of the underlying HIP layer. Such HIP-unaware 123 applications in some circumstances use HIP-based identifiers, such as 124 LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe 125 the identifier-locator bindings. 127 This document specifies extensions to [RFC3493] to define a new 128 socket address family, AF_HIP. The macro AF_HIP is used as an alias 129 for PF_HIP in this document because the distinction between AF and PF 130 has been lost in practice. The extensions also describe a new socket 131 address structure for sockets using Host Identity Tags (HITs) 132 explicitly and describe how the socket calls in [RFC3493] are adapted 133 or extended as a result. 135 Some applications may accept incoming communications from any 136 identifier. Other applications may initiate outgoing communications 137 without the knowledge of the peer identifier in Opportunistic Mode 138 [RFC5201] by just relying on a peer locator. This document describes 139 how to address both situations using "wildcards" as described later 140 in this document. 142 There are two related API documents. Multihoming and explicit 143 locator-handling related APIs are defined in 144 [I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes 145 and channel bindings APIs are defined in [I-D.ietf-btns-c-api]. Most 146 of the extensions defined in this document can be used independently 147 of the two mentioned related API documents. 149 The identity-locator split introduced by HIP introduces some policy 150 related challenges with datagram oriented sockets, opportunistic 151 mode, and manual bindings between HITs and locators. The extensions 152 in this document are of experimental nature and provide basic tools 153 for experimenting with policies. Policy related issues are left for 154 further experimentation. 156 To recap, the extensions in this document have three goals. The 157 first goal is to allow HIP-aware applications to open sockets to 158 other hosts based on the HITs alone, presuming that the underlying 159 system can resolve the HITs to addresses used for initial contact. 160 The second goal is that applications can explicitly initiate 161 communications with unknown peer identifiers. The third goal is to 162 define how HIP-aware applications may provide suggested initial 163 contact addresses along with the HITs. 165 2. Terminology 167 The terms used in this document are summarized in Table 1. 169 +---------+---------------------------------------------------------+ 170 | Term | Explanation | 171 +---------+---------------------------------------------------------+ 172 | HIP | Host Identity Protocol | 173 | HIT | Host Identity Tag, a 100-bit hash of a public key with | 174 | | a 28 bit prefix | 175 | LSI | Local Scope Identifier, a local, 32-bit descriptor for | 176 | | a given public key. | 177 | Locator | Routable IPv4 or IPv6 address used at the lower layers | 178 +---------+---------------------------------------------------------+ 180 Table 1 182 3. API Overview 184 This section provides an overview of how the API can be used. First, 185 the case in which a resolver is involved in name resolution is 186 described, and then the case in which no resolver is involved is 187 described. 189 3.1. Interaction with the Resolver 191 Before an application can establish network communications with the 192 entity named by a given FQDN or relative host name, the application 193 must translate the name into the corresponding identifier(s). DNS- 194 based hostname-to-identifier translation is illustrated in Figure 1. 195 The application calls the resolver in step a to resolve an FQDN step 196 b. The DNS server responds with a list of HITs and a set of locators 197 step c. Optionally in step d, the resolver caches the HIT to locator 198 mapping to the HIP module. The resolver returns the HITs to the 199 application step e. Finally, the application selects one HIT and 200 uses it in a socket call such as connect() in step f. 202 +----------+ 203 | | 204 | DNS | 205 | | 206 +----------+ 207 ^ | 208 b. | | c. 210 +-------------+ a. getaddrinfo() +----------+ 211 | |------------------------>| | 212 | Application | | Resolver | 213 | |<------------------------| | 214 +-------------+ e. +----------+ 215 | | 216 | | 217 | f. connect() | d. 218 v v 219 +----------+ +----------+ 220 | | | | 221 | TCP/IP | | HIP | 222 | Stack | | | 223 +----------+ +----------+ 225 Figure 1 227 In practice, the resolver functionality can be implemented in 228 different ways. For example, it may be implemented in existing 229 resolver libraries or as a DNS proxy. 231 3.2. Interaction without a Resolver 233 The extensions in this document focus on the use of the resolver to 234 map host names to HITs and locators in HIP-aware applications. The 235 resolver associates implicitly the HIT with the locator(s) by e.g. 236 communicating the HIT-to-IP mapping to the HIP daemon. However, it 237 is possible that an application operates directly on a peer HIT 238 without interacting with the resolver. In such a case, the 239 application may resort to the system to map the peer HIT to an IP 240 address. Alternatively, the application can explicitly map the HIT 241 to an IP address using socket options as specified in 242 [I-D.ietf-shim6-multihome-shim-api]. Full support for all of the 243 extensions defined in this draft requires shim socket options to be 244 implemented by the system. 246 4. API Syntax and Semantics 248 In this section, we describe the native HIP APIs using the syntax of 249 the C programming language. We limit the description to the 250 interfaces and data structures that are either modified or completely 251 new, because the native HIP APIs are otherwise identical to the 252 sockets API [POSIX]. 254 4.1. Socket Family and Address Structure Extensions 256 The sockets API extensions define a new protocol family, PF_HIP, and 257 a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to 258 each other. These definition shall be defined as a result of 259 including . 261 The use of the PF_HIP constant is mandatory with the socket() 262 function when an application uses the native HIP APIs. The 263 application gives the PF_HIP constant as the first argument (domain) 264 to the socket() function. The system returns a positive integer 265 representing a socket descriptor when the system supports HIP. 266 Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT. 268 Figure 2 shows socket address structure for HIP. 270 #include 272 typedef struct in6_addr hip_hit_t; 274 struct sockaddr_hip { 275 sa_family_t ship_family; 276 in_port_t ship_port; 277 uint32_t ship_pad; 278 uint64_t ship_flags; 279 hip_hit_t ship_hit; 280 uint8_t ship_reserved[16]; 281 }; 283 Figure 2 285 Figure 2 is in in 4.3BSD format. The family of the socket, 286 ship_family, is set to AF_HIP. The port number ship_port is two 287 octets in network byte order. and the ship_hit is 16 octets in 288 network byte order. An implementation may have extra member(s) in 289 this structure. 291 The application usually sets the ship_hit field using the resolver. 292 However, the application can use three special wildcard macros to set 293 a value directly into the ship_hit field. The macros are 294 HIP_HIT_ANY, HIP_HIT_ANY_PUB, HIP_HIT_ANY_TMP and HIP_ADDR_ANY. The 295 first three equal to a HIT value associated with a wildcard HIT of 296 any, public, or anonymous type. The fourth macro, HIP_ADDR_ANY, 297 denotes both HIP_HIT_ANY or any IPv4 or IPv6 address. The 298 HIP_HIT_ANY equals to HIP_HIT_ANY_PUB or HIP_HIT_ANY_TMP. The 299 anonymous identifiers refer to the use anonymous identifiers as 300 specified in [RFC4423]. The system may designate anonymous 301 identifiers as meta data associated with a HIT depending on whether 302 it has been published or not. However, there is no difference in the 303 classes of HITs from the HIP protocol perspective, 305 The application can use the HIP_HIT_ANY_* and HIP_ADDR_ANY macros to 306 accept incoming communications to all of the HITs of the local host. 307 Incoming communications refers here to the functions such as bind(), 308 recvfrom() and recvmsg(). The HIP_HIT_* macros are similar to the 309 sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are 310 applicable to HITs only. After initial contact with the peer, the 311 application can discover the local and peer HITs using getsockname() 312 and getpeername() calls in the context of connection oriented 313 sockets. The difference between the use of the HIP_HIT_* and 314 HIP_ADDR_ANY macros here is that the former allows only HIP-based 315 communications but the latter also allows communications without HIP. 317 The application also uses the HIP_HIT_ANY macro in ship_hit field to 318 establish outgoing communications in Opportunistic mode [RFC5201], 319 i.e., when the application knows the remote peer locator but not the 320 HIT. Outgoing communications refers here to the use of functions 321 such as connect(), sendto() and sendmsg(). However, the application 322 should first associate the socket with at least one IP address of the 323 peer using SHIM_LOCLIST_PEER_PREF socket option. The use of the 324 HIP_HIT_ANY macro guarantees that the communications will be based on 325 HIP or none at all. 327 The use of HIP_ADDR_ANY macro in the context of outgoing 328 communications is left for further experimentation. It could be used 329 for establishing a non-HIP based connectivity when HIP-based 330 connectivity was unsuccessful. 332 Some applications rely on system level access control, either 333 implicit or explicit (such as accept_filter() function found on BSD- 334 based systems), but such discussion is out of scope. Other 335 applications implement access control themselves by using the HITs. 336 In such a case, the application can compare two HITs using memcmp() 337 or similar function. It should be noticed that different connection 338 attempts between the same two hosts can result in different HITs 339 because a host is allowed to have multiple HITs. 341 4.2. Extensions to Resolver Data Structures 343 The HIP APIs introduce a new addrinfo flag, HIP_PREFER_ORCHID, to be 344 used by application to query for both HIT and locator information via 345 the getaddrinfo() resolver function [RFC3493]. The getaddrinfo() 346 function uses a data structure used for both input to and output from 347 the resolver. The data structure is illustrated in Figure 3. 349 #include 351 struct addrinfo { 352 int ai_flags; /* e.g. AI_EXTFLAGS */ 353 int ai_family; /* e.g. AF_HIP */ 354 int ai_socktype; /* e.g. SOCK_STREAM */ 355 int ai_protocol; /* 0 or IPPROTO_HIP */ 356 socklen_t ai_addrlen; /* size of *ai_addr */ 357 struct sockaddr *ai_addr; /* sockaddr_hip */ 358 char *ai_canonname; /* canon. name of the host */ 359 struct addrinfo *ai_next; /* next endpoint */ 360 int ai_eflags; /* RFC5014 extension */ 361 }; 363 Figure 3 365 Application must set both the flag AI_EXTFLAGS [RFC5014] in ai_flags 366 and HIP_PREFER_ORCHID in the ai_eflags, or otherwise the resolver 367 does not return sockaddr_hip data structures. The resolver returns 368 EAI_BADFLAGS when it does not support HIP_PREFER_ORCHID or 369 AI_EXTFLAGS flags. 371 The system may have a HIP-aware interposing DNS agent as described in 372 section 3.2 in [RFC5014]. In such a case, the DNS agent returns 373 transparently LSIs or HITs in sockaddr_in and sockaddr_in6 structures 374 when available. To disable this behaviour, the application sets 375 AI_EXTFLAGS and AI_NO_ORCHID flags. 377 Application denotes its preference for public and anonymous types of 378 HITs using HIP_PREFER_SRC_PUBLIC and HIP_PREFER_SRC_TMP flags in the 379 ai_eflags field. If the application sets neither of the flags, the 380 resolver returns both public and anonymous HITs. 382 The simultaneous use of both HIP_PREFER_ORCHID and 383 HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip structure 384 containing a wildcard address that the application can use either for 385 incoming (node argument is NULL in getaddrinfo) or outgoing 386 communications (node argument is non-NULL). For example, 387 HIP_PREFER_PASSIVE_HIT_TMP flag produces one sockaddr_hip structure 388 that contains a HIP_HIT_ANY_TMP in the ship_hit field. 390 The resolver sets the ai_family field to AF_HIP in the addrinfo 391 structure when ai_addr points to a sockaddr_hip structure. 393 When ai_protocol field is set to zero, the resolver also returns 394 locators in sockaddr_in and sockaddr_in6 structures in addition to 395 sockaddr_hip structures. The resolver returns only sockaddr_hip 396 structures when the application has set the ai_protocol field to 397 IPPROTO_HIP or a sockaddr_hip structure is given as the hint argument 398 to the resolver. 400 4.2.1. Resolver Usage 402 A HIP-aware application creates the sockaddr_hip structures 403 explicitly or obtains them from the resolver. The explicit 404 configuration of locators is described in 405 [I-D.ietf-shim6-multihome-shim-api]. This document defines 406 "automated" resolver extensions for getaddrinfo() resolver [RFC3493]. 408 #include 410 int getaddrinfo(const char *nodename, 411 const char *servname, 412 const struct addrinfo *hints, 413 struct addrinfo **res) 414 void free_addrinfo(struct addrinfo *res) 416 Figure 4 418 As described in [RFC3493], the getaddrinfo function takes the 419 nodename, servname, and hints as its input arguments. It places the 420 result of the query into the res argument. The return value is zero 421 on success, or a non-zero error value on error. The nodename 422 argument specifies the host name to be resolved; a NULL argument 423 denotes the local host. The servname parameter declares the port 424 number to be set in the socket addresses in the res output argument. 425 Both the nodename and servname cannot be NULL. 427 The input argument "hints" acts like a filter that defines the 428 attributes required from the resolved endpoints. A NULL hints 429 argument indicates that any kind of endpoints are acceptable. 431 The output argument "res" is dynamically allocated by the resolver. 432 The application frees res argument with the free_addrinfo function. 433 The res argument contains a linked list of the resolved endpoints. 434 The linked list contains sockaddr_hip structures only when the input 435 argument has the HIP_PREFER_ORCHID flag set in ai_eflags. The 436 resolver inserts HITs before any locators. When the 437 HIP_PREFER_ORCHID flag is set, the resolver does not return LSIs or 438 HITs encapsulated into sockaddr_in or sockaddr_in6 data structures as 439 described in [RFC5338]. 441 Resolver can return a HIT which maps to multiple locators. The 442 resolver may cache the locator mappings to the HIP module. The HIP 443 module manages the multiple locators according to system policies of 444 the host. The multihoming document 445 [I-D.ietf-shim6-multihome-shim-api] describes how an application can 446 override system default policies. 448 It should be noticed that the application can configure the HIT 449 explicitly without setting the locator or the resolver can fail to 450 resolve any locator. In this scenario, the application relies on the 451 system to map the HIT to an IP address. When the system fails to 452 provide the mapping, it returns -1 in the called sockets API function 453 to the application and sets errno to EADDRNOTAVAIL. 455 4.3. The Use of getsockname and getpeername Functions 457 The application usually discovers the local or peer HITs from the 458 sockaddr_hip structures returned by getaddrinfo(). However, the 459 sockaddr_hip structure does not contain a HIT when the application 460 uses the HIP_HIT_ANY_* macros. In such a case, the application 461 discovers the local and peer HITs using the getsockname() and 462 getpeername() functions. The functions return sockaddr_hip 463 structures when the family of the socket is AF_HIP. 465 4.4. Validating HITs 467 An application that uses the HIP_ADDR_ANY macro may want to check if 468 the local or peer address is an orchid-based HIT [RFC4843]. Also, 469 the application may want to verify whether a HIT is public or 470 anonymous. The application accomplishes these using a new function 471 called sockaddr_is_srcaddr() which is illustrated in Figure 5. 473 #include 475 short sockaddr_is_srcaddr(struct sockaddr *srcaddr 476 uint64_t flags); 478 Figure 5 480 The sockaddr_is_srcaddr() function operates in the same way as 481 inet6_is_srcaddr() function [RFC5014] which can be used to verify the 482 type of an address belonging to the localhost. The difference is 483 that sockaddr_is_srcaddr() function handles sockaddr_hip structures 484 in addition to sockaddr_in6, and possibly some other socket 485 structures in further extensions. The function has also 64 bit flags 486 instead of 32 bits. This new function handles the same flags as 487 defined in [RFC5014] in addition to some HIP-specific flags listed in 488 Table 2. 490 +-----------------------+-------------------------+ 491 | Flag | Purpose | 492 +-----------------------+-------------------------+ 493 | HIP_PREFER_ORCHID | The identifier is a HIT | 494 | HIP_PREFER_SRC_TMP | Anonymous HIT | 495 | HIP_PREFER_SRC_PUBLIC | Public HIT | 496 +-----------------------+-------------------------+ 498 Table 2 500 4.5. Source HIT Selection by the System 502 Some applications initiate communications by specifying only the 503 destination identifier and let the underlying system specify the 504 source. When the system selects the source HIT, the system should 505 apply the rules specified in [RFC3484] according to the default 506 policy table for HITs shown in Table 3. 508 +-----------------+------------+-------+ 509 | HIT Type | Precedence | Label | 510 +-----------------+------------+-------+ 511 | Anonymous DSA | 110 | 5 | 512 | Anonymous RSA | 120 | 6 | 513 | Public DSA | 130 | 7 | 514 | Public RSA | 140 | 8 | 515 | [RFC3484] rules | 50-100 | 7 | 516 +-----------------+------------+-------+ 518 Table 3 520 When application using a AF_HIP-based socket does not specify the 521 source identifier, the system selects the source identifier on the 522 behalf of the application according to the precedence in the above 523 table. For example, the system prefers public (published) keys 524 before anonymous keys because they work better for referral purposes. 525 RSA-based keys are preferred over DSA based because RSA is the 526 default algorithm in HIP. 528 When system provides multiple keys of same type, but with different 529 key lengths, the longer keys should have a higher preference. As 530 example, system providing two public RSA keys of different size would 531 give the smaller key preference value 140 and 145 for the larger. 532 The preference value should not exceed 150. Systems supporting more 533 than 10 keys of same key size may use digits to further fragment the 534 precedence namespace. IPv6 addresses have the lowest precedence 535 value to denote that HITs have a higher precedence when operating on 536 AF_HIP-based sockets. 538 [RFC5014] specifies flags for the getaddrinfo resolver and socket 539 options for Mobile IPv6. The resolver, operating under 540 HIP_PREFER_ORCHID flag, or the socket handler, operating on a AF_HIP- 541 based socket, may encounter such flags or options. In such a case 542 the resolver or socket handler should silenty ignore the flags or 543 options without returning an error. However, a HIP-aware application 544 may use the HIP-specific flags HIP_PREFER_ORCHID, HIP_PREFER_SRC_TMP 545 or HIP_PREFER_SRC_PUBLIC in getsockopt(), setsockopt(), getaddrinfo() 546 calls and in the anchillary data of datagram packets as specified in 547 [RFC5014]. The level of the socket options should be set to SOL_SHIM 548 [I-D.ietf-shim6-multihome-shim-api] and the option name should be 549 HIP_HIT_PREFERENCES. 551 4.6. Explicit Handling of Locators 553 The system resolver, or the HIP module, maps HITs to locators 554 implicitly. However, some applications may want to specify initial 555 locator mappings explicitly. In such a case, the application first 556 creates a socket with AF_HIP as the domain argument. Second, the 557 application may set locator information with one of the following 558 shim socket options as defined in the multihoming extensions in 559 [I-D.ietf-shim6-multihome-shim-api]: 561 +-----------------------------+-----+-----+-----------------+-------+ 562 | optname | get | set | description | dtype | 563 +-----------------------------+-----+-----+-----------------+-------+ 564 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 565 | | | | preferred | | 566 | | | | locator on the | | 567 | | | | local side for | | 568 | | | | the context | | 569 | | | | associated with | | 570 | | | | the socket. | | 571 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 572 | | | | preferred | | 573 | | | | locator on the | | 574 | | | | remote side for | | 575 | | | | the context | | 576 | | | | associated with | | 577 | | | | the socket. | | 578 | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *2 | 579 | | | | list of | | 580 | | | | locators | | 581 | | | | associated with | | 582 | | | | the local EID. | | 583 | SHIM_LOCLIST_PEER | o | o | Get or set a | *2 | 584 | | | | list of | | 585 | | | | locators | | 586 | | | | associated with | | 587 | | | | the peer's EID. | | 588 | SHIM_LOC_LOCAL_SEND | o | o | Request use of | *2 | 589 | | | | specific | | 590 | | | | locator as | | 591 | | | | source locator | | 592 | | | | of outgoing IP | | 593 | | | | packets. | | 594 | SHIM_LOC_PEER_SEND | o | o | Request use of | *2 | 595 | | | | specific | | 596 | | | | locator as | | 597 | | | | destination | | 598 | | | | locator of | | 599 | | | | outgoing IP | | 600 | | | | packets. | | 601 +-----------------------------+-----+-----+-----------------+-------+ 602 *1: Pointer to a shim_locator which is defined in Section 7 of 603 draft-ietf-shim6-multihome-shim-api. 604 *2: Pointer to an array of shim_locator. 606 Figure 6 608 Finally, the application creates a valid sockaddr_hip structure and 609 associates the socket also with the sockaddr_hip structure by calling 610 some socket-related function, such as connect() or bind(). 612 The usage and semantics for typical use cases are as follows: 614 An application that initiates a connection using a connection 615 oriented socket to a particular host at a known address or set of 616 addresses can invoke SHIM_LOCLIST_PEER socket option. The HIP module 617 uses the first address (if multiple are provided, or else the 618 application can override this by setting SHIM_LOC_PEER_PREF to one of 619 the addresses in SHIM_LOCLIST_PEER. The application later provides a 620 specific HIT in the ship_hit field of the sockaddr_hip in the 621 connect() system call. If the application provides one or more 622 addresses in SHIM_LOCLIST_PEER setsockopt call, the system should not 623 connect to the host via another destination address, in case the 624 application intends to restrict the range of addresses permissible as 625 a policy choice. If the system cannot reach the provided HIT at one 626 of the addresses provided, the outbound socket API functions 627 (connect, sendmsg, etc.) return -1 and set errno to EINVALIDLOCATOR. 629 Another common use case is to set up an association in opportunistic 630 mode, when the destination HIT is specified as a wildcard. This can 631 be accomplished by setting one or more destination addresses using 632 the SHIM_LOCLIST_PEER socket option as described above and then 633 calling connect() with the wildcard HIT. The connect() call returns 634 -1 and sets errno to EADDRNOTAVAIL when the application connects to a 635 wildcard without specifying any destination address. 637 Applications may also choose to associate local addresses with 638 sockets. The procedures specified in 639 [I-D.ietf-shim6-multihome-shim-api] are followed in this case. 641 5. Summary of New Definitions 643 Table 4 summarizes the new macro and structures defined in this 644 document. 646 +-----------------+-----------------------------+ 647 | Header | Definition | 648 +-----------------+-----------------------------+ 649 | | AF_HIP | 650 | | PF_HIP | 651 | | IPPROTO_HIP | 652 | | HIP_HIT_ANY | 653 | | HIP_HIT_ANY_PUB | 654 | | HIP_HIT_ANY_TMP | 655 | | HIP_ADDR_ANY | 656 | | HIP_HIT_PREFERENCES | 657 | | hip_hit_t | 658 | | HIP_PREFER_ORCHID | 659 | | HIP_PREFER_SRC_TMP | 660 | | HIP_PREFER_SRC_PUBLIC | 661 | | HIP_PREFER_PASSIVE_HIT_TMP | 662 | | HIP_PREFER_PASSIVE_HIT_PUB | 663 | | HIP_PREFER_PASSIVE_HIT_ANY | 664 | | HIP_PREFER_PASSIVE_ADDR_ANY | 665 | | sockaddr_hip | 666 | | sockaddr_is_srcaddr | 667 +-----------------+-----------------------------+ 669 Table 4 671 6. IANA Considerations 673 No IANA considerations. 675 7. Security Considerations 677 No security considerations currently. 679 8. Contributors 681 Thanks for Jukka Ylitalo and Pekka Nikander for their original 682 contribution, time and effort to the native HIP APIs. Thanks for 683 Yoshifuji Hideaki for his contributions to this document. 685 9. Acknowledgements 687 Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan 688 Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti 689 Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen, 690 Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and 691 Gonzalo Camarillo have also provided valuable ideas or feedback. 692 Thanks also for the APPS area folks, including Stephane Bortzmeyer, 693 Chris Newman, Tony Finch, "der Mouse" and Keith Moore. 695 10. Normative References 697 [I-D.ietf-btns-c-api] 698 Richardson, M., Williams, N., Komu, M., and S. Tarkoma, 699 "C-Bindings for IPsec Application Programming Interfaces", 700 draft-ietf-btns-c-api-04 (work in progress), March 2009. 702 [I-D.ietf-shim6-multihome-shim-api] 703 Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, 704 "Socket Application Program Interface (API) for 705 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-08 706 (work in progress), May 2009. 708 [I-D.ietf-shim6-proto] 709 Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 710 Shim Protocol for IPv6", draft-ietf-shim6-proto-12 (work 711 in progress), February 2009. 713 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 714 Std. 1003.1-2001 Standard for Information Technology - 715 Portable Operating System Interface (POSIX)", Dec 2001. 717 [RFC3484] Draves, R., "Default Address Selection for Internet 718 Protocol version 6 (IPv6)", RFC 3484, February 2003. 720 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 721 Stevens, "Basic Socket Interface Extensions for IPv6", 722 RFC 3493, February 2003. 724 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 725 (HIP) Architecture", RFC 4423, May 2006. 727 [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix 728 for Overlay Routable Cryptographic Hash Identifiers 729 (ORCHID)", RFC 4843, April 2007. 731 [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 732 Socket API for Source Address Selection", RFC 5014, 733 September 2007. 735 [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, 736 "Host Identity Protocol", RFC 5201, April 2008. 738 [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol 739 (HIP) Domain Name System (DNS) Extensions", RFC 5205, 740 April 2008. 742 [RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host 743 Identity Protocol with Legacy Applications", RFC 5338, 744 September 2008. 746 Authors' Addresses 748 Miika Komu 749 Helsinki Institute for Information Technology 750 Metsaenneidonkuja 4 751 Helsinki 752 Finland 754 Phone: +358503841531 755 Fax: +35896949768 756 Email: miika@iki.fi 757 URI: http://www.iki.fi/miika/ 759 Thomas Henderson 760 The Boeing Company 761 P.O. Box 3707 762 Seattle, WA 763 USA 765 Email: thomas.r.henderson@boeing.com