idnits 2.17.1 draft-ietf-hip-native-api-07.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 366 has weird spacing: '... struct soc...' == Line 368 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, 2009) is 5394 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 285 == Outdated reference: A later version (-17) exists of draft-ietf-shim6-multihome-shim-api-08 ** 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: 5 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: January 14, 2010 Henderson 6 The Boeing Company 7 July 13, 2009 9 Basic Socket Interface Extensions for Host Identity Protocol (HIP) 10 draft-ietf-hip-native-api-07 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 January 14, 2010. 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 the 52 Host Identity Protocol (HIP). The extensions focus on the use of 53 public-key based identifiers discovered via DNS resolution, but 54 define also interfaces for manual bindings between HITs and locators. 55 With the extensions, the application can also support more relaxed 56 security models where the communication can be non-HIP based, 57 according to local policies. The extensions in document are 58 experimental and provide basic tools for further experimentation with 59 policies. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. API Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.1. Interaction with the Resolver . . . . . . . . . . . . . . 5 67 3.2. Interaction without a Resolver . . . . . . . . . . . . . . 6 68 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 7 69 4.1. Socket Family and Address Structure Extensions . . . . . . 7 70 4.2. Extensions to Resolver Data Structures . . . . . . . . . . 9 71 4.3. The Use of getsockname and getpeername Functions . . . . . 11 72 4.4. Selection of Source HIT Type . . . . . . . . . . . . . . . 11 73 4.5. Verification of Source HIT Type . . . . . . . . . . . . . 12 74 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 12 75 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 14 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 78 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 14 79 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 80 10. Normative References . . . . . . . . . . . . . . . . . . . . . 15 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 83 1. Introduction 85 This document defines C-based sockets Application Programming 86 Interface (API) extensions for handling HIP-based identifiers 87 explicitly in HIP-aware applications. It is up to the applications, 88 or high-level programming languages or libraries, to manage the 89 identifiers. The extensions in this document are mainly related to 90 the use case in which a DNS resolution step has occurred prior to the 91 creation of a new socket, and assumes that the system has cached or 92 is otherwise able to resolve identifiers to locators (IP addresses). 93 The DNS extensions for HIP are described in [RFC5205]. The 94 extensions also cover the case in which an application may want to 95 explicitly provide suggested locators with the identifiers, including 96 supporting the opportunistic case in which the system does not know 97 the peer host identity. 99 The Host Identity Protocol (HIP) [RFC4423] proposes a new 100 cryptographic namespace by separating the roles of end-point 101 identifiers and locators by introducing a new namespace to the TCP/IP 102 stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on 103 identity-locator split. The APIs specified in this document are 104 specific to HIP, but have been designed as much as possible so as not 105 to preclude its use with other protocols. The use of these APIs with 106 other protocols is, nevertheless, for further study. 108 The APIs in this document are based on IPv6 addresses with the ORCHID 109 prefix [RFC4843]. ORCHIDs are derived from Host Identifiers using a 110 hash and fitting the result into an IPv6 address. Such addresses are 111 called Host Identity Tags (HITs) and they can be distinguished from 112 other IPv6 addresses with the ORCHID prefix. 114 Applications can observe the HIP layer and its identifiers in the 115 networking stacks with varying degrees of visibility. [RFC5338] 116 discusses the lowest levels of visibility in which applications are 117 completely unaware of the underlying HIP layer. Such HIP-unaware 118 applications in some circumstances use HIP-based identifiers, such as 119 LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe 120 the identifier-locator bindings. 122 This document specifies extensions to [RFC3493] to define a new 123 socket address family, AF_HIP. Similarly to other address families, 124 AF_HIP can used as an alias for PF_HIP. The extensions also describe 125 a new socket address structure for sockets using HITs explicitly and 126 describe how the socket calls in [RFC3493] are adapted or extended as 127 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 (section 4.1.6 in [RFC5201]) by just relying on a peer locator. This 133 document describes how to address both situations using "wildcards" 134 as 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 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 an experimental nature and provide basic 147 tools for experimenting with policies. Policy related issues are 148 left for 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 illustrate how HIP-aware applications can use the SHIM API 157 [I-D.ietf-shim6-multihome-shim-api] to manually map locators to 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 to 190 HIT(s). The resolver queries the DNS in step (b) to map the FQDN to 191 a host identifier and locator (A and AAAA records). It should be 192 noticed that the FQDN may map to multiple host identifiers and 193 locators, and this step may involve multiple DNS transactions, 194 including queries for A, AAAA, HI and possibly other resource 195 records. The DNS server responds with a list of HIP resource records 196 in step (c). Optionally in step (d), the resolver caches the HIT to 197 locator mapping with the HIP module. The resolver converts the HIP 198 records to HITs and returns the HITs to the application contained in 199 HIP socket address structures in step (e). Depending on the 200 parameters for the resolver call, the resolver may return also other 201 socket address structures to the application. Finally, the 202 application receives the socket address structure(s) from the 203 resolver and uses them in socket calls such as connect() in step (f). 205 +----------+ 206 | | 207 | DNS | 208 | | 209 +----------+ 210 ^ | 211 b. QNAME=FQDN | | c. HIP and 212 | | A/AAAA 213 | v RR(s) 214 +-------------+ a. getaddrinfo() +----------+ 215 | |------------------------>| | 216 | Application | | Resolver | 217 | |<------------------------| | 218 +-------------+ e. +----------+ 219 | | 220 | | d. HIP and 221 | f. connect() | A/AAAA 222 | or any other socket call | RR(s) 223 v v 224 +----------+ +----------+ 225 | | | | 226 | TCP/IP | | HIP | 227 | Stack | | | 228 +----------+ +----------+ 230 Figure 1 232 In practice, the resolver functionality can be implemented in 233 different ways. For example, it may be implemented in existing 234 resolver libraries or as a HIP-aware interposing agent. 236 3.2. Interaction without a Resolver 238 The extensions in this document focus on the use of the resolver to 239 map host names to HITs and locators in HIP-aware applications. The 240 resolver may implicitly associate a HIT with the corresponding 241 locator(s) by communicating the HIT-to-IP mapping to the HIP daemon. 242 However, it is possible that an application operates directly on a 243 peer HIT without interacting with the resolver. In such a case, the 244 application may resort to the system to map the peer HIT to an IP 245 address. Alternatively, the application can explicitly map the HIT 246 to an IP address using socket options as specified in Section 4.6. 247 Full support for all of the extensions defined in this draft requires 248 a number of shim socket options [I-D.ietf-shim6-multihome-shim-api] 249 to be implemented by the system. 251 4. API Syntax and Semantics 253 In this section, we describe the native HIP APIs using the syntax of 254 the C programming language. We limit the description to the 255 interfaces and data structures that are either modified or completely 256 new, because the native HIP APIs are otherwise identical to the 257 sockets API [POSIX]. 259 4.1. Socket Family and Address Structure Extensions 261 The sockets API extensions define a new protocol family, PF_HIP, and 262 a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to 263 each other. These definition shall be defined as a result of 264 including . 266 The use of the PF_HIP constant is mandatory with the socket() 267 function when an application uses the native HIP APIs. The 268 application gives the PF_HIP constant as the first argument (domain) 269 to the socket() function. The system returns a positive integer 270 representing a socket descriptor when the system supports HIP. 271 Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT. 273 Figure 2 shows socket address structure for HIP. 275 #include 277 typedef struct in6_addr hip_hit_t; 279 struct sockaddr_hip { 280 sa_family_t ship_family; 281 in_port_t ship_port; 282 uint32_t ship_pad; 283 uint64_t ship_flags; 284 hip_hit_t ship_hit; 285 uint8_t ship_reserved[16]; 286 }; 288 Figure 2 290 Figure 2 is in in 4.3BSD format. The family of the socket, 291 ship_family, is set to AF_HIP. The port number ship_port is two 292 octets in network byte order and the ship_hit is 16 octets in network 293 byte order. An implementation may have extra member(s) in this 294 structure. 296 The application usually sets the ship_hit field using the resolver. 297 However, the application can use three special constants to set a 298 wildcard value manually into the ship_hit field. The constants are 299 HIP_HIT_ANY, HIP_HIT_ANY_PUB, HIP_HIT_ANY_TMP and HIP_ENDPOINT_ANY. 300 The first three equal to a HIT value associated with a wildcard HIT 301 of any type, public type, or anonymous type. The fourth constant, 302 HIP_ENDPOINT_ANY, denotes that the application accepts both HIT and 303 any other type of addresses. The HIP_HIT_ANY denotes that the 304 application accepts any type of HIT. The anonymous identifiers refer 305 to the use of anonymous identifiers as specified in [RFC4423]. The 306 system may designate anonymous identifiers as meta data associated 307 with a HIT depending on whether it has been published or not. 308 However, there is no difference in the classes of HITs from the 309 protocol perspective. 311 The application can use the HIP_HIT_ANY_* and HIP_ENDPOINT_ANY 312 constants to accept incoming communications to all of the HITs of the 313 local host. Incoming communications refers here to functions such as 314 bind(), recvfrom() and recvmsg(). The HIP_HIT_* constants are 315 similar to the sockets API constants INADDR_ANY and IN6ADDR_ANY_INIT, 316 but they are applicable to HITs only. After initial contact with the 317 peer, the application can discover the local and peer HITs using 318 getsockname() and getpeername() calls in the context of connection 319 oriented sockets. The difference between the use of the HIP_HIT_* 320 and HIP_ENDPOINT_ANY constants here is that the former allows only 321 HIP-based communications but the latter also allows communications 322 without HIP. 324 The application also uses the HIP_HIT_ANY constant in ship_hit field 325 to establish outgoing communications in Opportunistic mode [RFC5201], 326 i.e., when the application knows the remote peer locator but not the 327 HIT. Outgoing communications refers here to the use of functions 328 such as connect(), sendto() and sendmsg(). However, the application 329 should first associate the socket with at least one IP address of the 330 peer using SHIM_LOCLIST_PEER_PREF socket option. The use of the 331 HIP_HIT_ANY constant guarantees that the communications will be based 332 on HIP or none at all. 334 The use of HIP_ENDPOINT_ANY constant in the context of outgoing 335 communications is left for further experimentation in the context of 336 opportunistic mode. It can result in a data flow with or without 337 HIP. 339 Some applications rely on system level access control, either 340 implicit or explicit (such as accept_filter() function found on BSD- 341 based systems), but such discussion is out of scope. Other 342 applications implement access control themselves by using the HITs. 343 In such a case, the application can compare two HITs contained in the 344 ship_hit field using memcmp() or similar function. It should be 345 noted that different connection attempts between the same two hosts 346 can result in different HITs because a host is allowed to have 347 multiple HITs. 349 4.2. Extensions to Resolver Data Structures 351 The HIP APIs introduce a new address family, AF_HIP, that HIP aware 352 applications can use to control the address type returned from 353 getaddrinfo() function [RFC3493]. The getaddrinfo() function uses a 354 data structure called addrinfo in its "hints" and "res" argument 355 which are described in more detail in the next section. The addrinfo 356 data structure is illustrated in Figure 3. 358 #include 360 struct addrinfo { 361 int ai_flags; /* e.g. AI_EXTFLAGS */ 362 int ai_family; /* e.g. AF_HIP */ 363 int ai_socktype; /* e.g. SOCK_STREAM */ 364 int ai_protocol; /* 0 or IPPROTO_HIP */ 365 socklen_t ai_addrlen; /* size of *ai_addr */ 366 struct sockaddr *ai_addr; /* sockaddr_hip */ 367 char *ai_canonname; /* canon. name of the host */ 368 struct addrinfo *ai_next; /* next endpoint */ 369 int ai_eflags; /* RFC5014 extension */ 370 }; 372 Figure 3 374 An application resolving with the ai_family field set to AF_UNSPEC in 375 the hints argument may receive any kind of socket address structures, 376 including sockaddr_hip. When the application wants to receive only 377 HITs contained in sockaddr_hip structures, it should set the 378 ai_family field to AF_HIP. Otherwise, the resolver does not return 379 any sockaddr_hip structures. The resolver returns EAI_FAMILY when 380 AF_HIP is not supported. 382 The resolver ignores the AI_PASSIVE flag when the application sets 383 the family in hints to AF_HIP. 385 The system may have a HIP-aware interposing DNS agent as described in 386 section 3.2 in [RFC5338]. In such a case, the DNS agent may, 387 according to local policy, return transparently LSIs or HITs in 388 sockaddr_in and sockaddr_in6 structures when available. A HIP-aware 389 application can override this local policy in two ways. First, the 390 application can set the family to AF_HIP in the hints argument of 391 getaddrinfo() when it requests only sockaddr_hip structures. Second, 392 the application can set AI_EXTFLAGS and AI_NO_HIT flags to prevent 393 the resolver from returning HITs in any kind of data structures. 395 When getaddrinfo() returns resolved outputs the results to res 396 argument, it sets the family to AF_HIP when the related structure is 397 sockaddr_hip. 399 4.2.1. Resolver Usage 401 A HIP-aware application creates the sockaddr_hip structures manually 402 or obtains them from the resolver. The explicit configuration of 403 locators is described in [I-D.ietf-shim6-multihome-shim-api]. This 404 document defines "automated" resolver extensions for getaddrinfo() 405 resolver [RFC3493]. 407 #include 409 int getaddrinfo(const char *nodename, 410 const char *servname, 411 const struct addrinfo *hints, 412 struct addrinfo **res) 413 void free_addrinfo(struct addrinfo *res) 415 Figure 4 417 As described in [RFC3493], the getaddrinfo function takes the 418 nodename, servname, and hints as its input arguments. It places the 419 result of the query into the res output argument. The return value 420 is zero on success, or a non-zero error value on error. The nodename 421 argument specifies the host name to be resolved; a NULL argument 422 denotes the HITs of the local host. The servname parameter declares 423 the port number to be set in the socket addresses in the res output 424 argument. Both the nodename and servname cannot be NULL at the same 425 time. 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 the res argument with the free_addrinfo 433 function. The res argument contains a linked list of the resolved 434 endpoints. The linked list contains sockaddr_hip structures only 435 when the input argument has the family set to AF_HIP. When the 436 family is zero, the list contains sockaddr_hip structures before 437 sockaddr_in and sockaddr_in6 structures. 439 Resolver can return a HIT which maps to multiple locators. The 440 resolver may cache the locator mappings with the HIP module. The HIP 441 module manages the multiple locators according to system policies of 442 the host. The multihoming document 444 [I-D.ietf-shim6-multihome-shim-api] describes how an application can 445 override system default policies. 447 It should be noted that the application can configure the HIT 448 explicitly without setting the locator or the resolver can fail to 449 resolve any locator. In this scenario, the application relies on the 450 system to map the HIT to an IP address. When the system fails to 451 provide the mapping, it returns -1 in the called sockets API function 452 to the application and sets errno to EADDRNOTAVAIL. 454 4.3. The Use of getsockname and getpeername Functions 456 The application usually discovers the local or peer HITs from the 457 sockaddr_hip structures returned by getaddrinfo(). However, the 458 sockaddr_hip structure does not contain a HIT when the application 459 uses the HIP_HIT_ANY_* constants. In such a case, the application 460 discovers the local and peer HITs using the getsockname() and 461 getpeername() functions. The functions return sockaddr_hip 462 structures when the family of the socket is AF_HIP. 464 4.4. Selection of Source HIT Type 466 The Socket API for Source Address Selection [RFC5014] defines socket 467 options to allow applications to influence source address selection 468 mechanisms. In some cases, HIP-aware applications may want to 469 influence source HIT selection; in particular, whether an outbound 470 connection should use a published or anonymous HIT. Similar to 471 IPV6_ADDR_PREFERENCES defined in RFC 5014, the following socket 472 option HIT_PREFERENCES is defined for HIP-based sockets. This socket 473 option can be used with setsockopt() and getsockopt() calls to set 474 and get the HIT selection preferences affecting a HIP-enabled socket. 475 The socket option value (optval) is a 32-bit unsigned integer 476 argument. The argument consists of a number of flags where each flag 477 indicates an address selection preference that modifies one of the 478 rules in the default HIT selection; these flags are shown in Table 2. 480 +---------------------------+-------------------------+ 481 | Socket Option | Purpose | 482 +---------------------------+-------------------------+ 483 | HIP_PREFER_SRC_HIT_TMP | Prefer an anonymous HIT | 484 | HIP_PREFER_SRC_HIT_PUBLIC | Prefer a public HIT | 485 +---------------------------+-------------------------+ 487 Table 2 489 If the system is unable to assign the type of HIT that is requested, 490 at HIT selection time, the socket call (connect (), sendto(), or 491 sendmsg()) will fail and errno will be set to EINVAL. If the 492 application tries to set both of the above flags for the same socket, 493 this also results in the error EINVAL. 495 4.5. Verification of Source HIT Type 497 An application that uses the HIP_ENDPOINT_ANY constant may want to 498 check whether the actual communications was based on HIP or not. 499 Also, the application may want to verify whether a local HIT is 500 public or anonymous. The application accomplishes these using a new 501 function called sockaddr_is_srcaddr() which is illustrated in 502 Figure 5. 504 #include 506 short sockaddr_is_srcaddr(struct sockaddr *srcaddr, 507 uint64_t flags); 509 Figure 5 511 The sockaddr_is_srcaddr() function operates in the same way as 512 inet6_is_srcaddr() function [RFC5014] which can be used to verify the 513 type of an address belonging to the local host. The difference is 514 that the sockaddr_is_srcaddr() function handles sockaddr_hip 515 structures in addition to sockaddr_in6, and possibly some other 516 socket structures in further extensions. The flags argument is also 517 64 bit instead of 32 bits because new function handles the same flags 518 as defined in [RFC5014] in addition to two HIP-specific flags, 519 HIP_PREFER_SRC_HIT_TMP and HIP_PREFER_SRC_HIT_PUBLIC. With these two 520 flags, the application can distinguish anonymous HITs from public 521 HITs. 523 When given an AF_INET6 socket, sockaddr_is_srcaddr() behaves as 524 inet6_is_srcaddr() function as described in [RFC5014]. With AF_HIP 525 socket, the function returns 1 when the HIT contained in the socket 526 address structure corresponds to a valid HIT of the local host and 527 the HIT satisfies the given flags. The function returns -1 when the 528 HIT does not belong to the local host or the flags are not valid. 529 The function returns 0 when the preference flags are valid but the 530 HIT does not match the given flags. 532 4.6. Explicit Handling of Locators 534 The system resolver, or the HIP module, maps HITs to locators 535 implicitly. However, some applications may want to specify initial 536 locator mappings explicitly. In such a case, the application first 537 creates a socket with AF_HIP as the domain argument. Second, the 538 application may get or set locator information with one of the 539 following shim socket options as defined in the multihoming 540 extensions in [I-D.ietf-shim6-multihome-shim-api]. The related 541 socket options are summarized briefly in Table 3. 543 +---------------------+---------------------------------------------+ 544 | optname | description | 545 +---------------------+---------------------------------------------+ 546 | SHIM_LOC_LOCAL_PREF | Get or set the preferred locator on the | 547 | | local side for the context associated with | 548 | | the socket. | 549 | SHIM_LOC_PEER_PREF | Get or set the preferred locator on the | 550 | | remote side for the context associated with | 551 | | the socket. | 552 | SHIM_LOCLIST_LOCAL | Get or set a list of locators associated | 553 | | with the local EID. | 554 | SHIM_LOCLIST_PEER | Get or set a list of locators associated | 555 | | with the peer's EID. | 556 | SHIM_LOC_LOCAL_SEND | Set or get the default source locator of | 557 | | outgoing IP packets. | 558 | SHIM_LOC_PEER_SEND | Set or get the default destination locator | 559 | | of outgoing IP packets. | 560 +---------------------+---------------------------------------------+ 562 Table 3 564 As an example of locator mappings, a connection-oriented application 565 creates a HIP-based socket and sets the SHIM_LOCLIST_PEER socket 566 option to the socket. The HIP module uses the first address 567 contained in the option if multiple are provided. If the application 568 provides one or more addresses in the SHIM_LOCLIST_PEER setsockopt 569 call, the system should not connect to the host via another 570 destination address, in case the application intends to restrict the 571 range of addresses permissible as a policy choice. The application 572 can override the default peer locator by setting the 573 SHIM_LOC_PEER_PREF socket option if necessary. Finally, the 574 application provides a specific HIT in the ship_hit field of the 575 sockaddr_hip in the connect() system call. If the system cannot 576 reach the HIT at one of the addresses provided, the outbound socket 577 API functions (connect, sendmsg, etc.) return -1 and set errno to 578 EINVALIDLOCATOR. 580 Applications may also choose to associate local addresses with 581 sockets. The procedures specified in 582 [I-D.ietf-shim6-multihome-shim-api] are followed in this case. 584 Another use case is to use the opportunistic mode when the 585 destination HIT is specified as a wildcard. The application sets one 586 or more destination addresses using the SHIM_LOCLIST_PEER socket 587 option as described above and then calls connect() with the wildcard 588 HIT. The connect() call returns -1 and sets errno to EADDRNOTAVAIL 589 when the application connects to a wildcard without specifying any 590 destination address. 592 Applications using datagram-oriented sockets can use ancillary data 593 to control the locators. This described in detail in 594 [I-D.ietf-shim6-multihome-shim-api]. 596 5. Summary of New Definitions 598 Table 4 summarizes the new constants and structures defined in this 599 document. 601 +-----------------+---------------------+ 602 | Header | Definition | 603 +-----------------+---------------------+ 604 | | AF_HIP | 605 | | PF_HIP | 606 | | IPPROTO_HIP | 607 | | HIP_HIT_ANY | 608 | | HIP_HIT_ANY_PUB | 609 | | HIP_HIT_ANY_TMP | 610 | | HIP_ENDPOINT_ANY | 611 | | HIP_HIT_PREFERENCES | 612 | | hip_hit_t | 613 | | AI_NO_HIT | 614 | | sockaddr_hip | 615 | | sockaddr_is_srcaddr | 616 +-----------------+---------------------+ 618 Table 4 620 6. IANA Considerations 622 No IANA considerations. 624 7. Security Considerations 626 No security considerations currently. 628 8. Contributors 630 Thanks for Jukka Ylitalo and Pekka Nikander for their original 631 contribution, time and effort to the native HIP APIs. Thanks for 632 Yoshifuji Hideaki for his contributions to this document. 634 9. Acknowledgements 636 Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan 637 Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti 638 Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keranen, 639 Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Joakim Koskela, 640 Jeff Ahrenholz and Gonzalo Camarillo have also provided valuable 641 ideas or feedback. Thanks also for the APPS area folks, including 642 Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and Keith 643 Moore. 645 10. Normative References 647 [I-D.ietf-btns-c-api] 648 Richardson, M., Williams, N., Komu, M., and S. Tarkoma, 649 "C-Bindings for IPsec Application Programming Interfaces", 650 draft-ietf-btns-c-api-04 (work in progress), March 2009. 652 [I-D.ietf-shim6-multihome-shim-api] 653 Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, 654 "Socket Application Program Interface (API) for 655 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-08 656 (work in progress), May 2009. 658 [I-D.ietf-shim6-proto] 659 Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 660 Shim Protocol for IPv6", draft-ietf-shim6-proto-12 (work 661 in progress), February 2009. 663 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 664 Std. 1003.1-2001 Standard for Information Technology - 665 Portable Operating System Interface (POSIX)", Dec 2001. 667 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 668 Stevens, "Basic Socket Interface Extensions for IPv6", 669 RFC 3493, February 2003. 671 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 672 (HIP) Architecture", RFC 4423, May 2006. 674 [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix 675 for Overlay Routable Cryptographic Hash Identifiers 676 (ORCHID)", RFC 4843, April 2007. 678 [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 679 Socket API for Source Address Selection", RFC 5014, 680 September 2007. 682 [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, 683 "Host Identity Protocol", RFC 5201, April 2008. 685 [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol 686 (HIP) Domain Name System (DNS) Extensions", RFC 5205, 687 April 2008. 689 [RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host 690 Identity Protocol with Legacy Applications", RFC 5338, 691 September 2008. 693 Authors' Addresses 695 Miika Komu 696 Helsinki Institute for Information Technology 697 Metsanneidonkuja 4 698 Helsinki 699 Finland 701 Phone: +358503841531 702 Fax: +35896949768 703 Email: miika@iki.fi 704 URI: http://www.iki.fi/miika/ 706 Thomas Henderson 707 The Boeing Company 708 P.O. Box 3707 709 Seattle, WA 710 USA 712 Email: thomas.r.henderson@boeing.com