idnits 2.17.1 draft-ietf-hip-native-api-09.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 393 has weird spacing: '... struct soc...' == Line 395 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 (September 10, 2009) is 5341 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 ---------------------------------------------------------------------------- == Outdated reference: A later version (-17) exists of draft-ietf-shim6-multihome-shim-api-09 ** 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 (==), 3 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: March 14, 2010 Henderson 6 The Boeing Company 7 September 10, 2009 9 Basic Socket Interface Extensions for Host Identity Protocol (HIP) 10 draft-ietf-hip-native-api-09 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 March 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 this 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. Name Resolution Process . . . . . . . . . . . . . . . . . . . 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 . . . . . 12 72 4.4. Selection of Source HIT Type . . . . . . . . . . . . . . . 12 73 4.5. Verification of HIT Type . . . . . . . . . . . . . . . . . 13 74 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 14 75 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 15 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 78 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 17 79 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 80 10. Normative References . . . . . . . . . . . . . . . . . . . . . 17 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 83 1. Introduction 85 This document defines the 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 an 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 via 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 be used as an alias for PF_HIP. The extensions also 125 describe a new socket address structure for sockets using 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 (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 in Section 4.1.1. 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 binding 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. Name Resolution Process 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 one or more socket addresses within the PF_HIP family. The resolver, 191 in turn, queries the DNS in step (b) to map the FQDN to one or more 192 HIP RRs with the HIT and HI and possibly rendezvous server of the 193 Responder, and also (in parallel or sequentially) to resolve the FQDN 194 into possibly one or more A and AAAA records. It should be noted 195 that the FQDN may map to multiple host identifiers and locators, and 196 this step may involve multiple DNS transactions, including queries 197 for A, AAAA, HI and possibly other resource records. The DNS server 198 responds with a list of HIP resource records in step (c). Optionally 199 in step (d), the resolver caches the HIT-to-locator mapping with the 200 HIP module. The resolver converts the HIP records to HITs and 201 returns the HITs to the application contained in HIP socket address 202 structures in step (e). Depending on the parameters for the resolver 203 call, the resolver may return also other socket address structures to 204 the application. Finally, the application receives the socket 205 address structure(s) from the resolver and uses them in socket calls 206 such as connect() in step (f). 208 +----------+ 209 | | 210 | DNS | 211 | | 212 +----------+ 213 ^ | 214 b. QNAME=FQDN | | c. HIP and 215 | | A/AAAA 216 | v RR(s) 217 +-------------+ a. getaddrinfo() +----------+ 218 | |------------------------>| | 219 | Application | | Resolver | 220 | |<------------------------| | 221 +-------------+ e. +----------+ 222 | | 223 | | d. HIP and 224 | f. connect() | A/AAAA 225 | or any other socket call | RR(s) 226 v v 227 +----------+ +----------+ 228 | | | | 229 | TCP/IP | | HIP | 230 | Stack | | | 231 +----------+ +----------+ 233 Figure 1 235 In practice, the resolver functionality can be implemented in 236 different ways. For example, it may be implemented in existing 237 resolver libraries or as a HIP-aware interposing agent. 239 3.2. Interaction without a Resolver 241 The extensions in this document focus on the use of the resolver to 242 map host names to HITs and locators in HIP-aware applications. The 243 resolver may implicitly associate a HIT with the corresponding 244 locator(s) by communicating the HIT-to-IP mapping to the HIP daemon. 245 However, it is possible that an application operates directly on a 246 peer HIT without interacting with the resolver. In such a case, the 247 application may resort to the system to map the peer HIT to an IP 248 address. Alternatively, the application can explicitly map the HIT 249 to an IP address using socket options as specified in Section 4.6. 250 Full support for all of the extensions defined in this draft requires 251 a number of shim socket options [I-D.ietf-shim6-multihome-shim-api] 252 to be implemented by the system. 254 4. API Syntax and Semantics 256 In this section, we describe the native HIP APIs using the syntax of 257 the C programming language. We limit the description to the 258 interfaces and data structures that are either modified or completely 259 new because the native HIP APIs are otherwise identical to the 260 sockets API [POSIX]. 262 4.1. Socket Family and Address Structure Extensions 264 The sockets API extensions define a new protocol family, PF_HIP, and 265 a new address family, AF_HIP. The AF_HIP and PF_HIP constants are 266 aliases to each other. These definitions shall be defined as a 267 result of including . 269 When the socket() function is called with PF_HIP as the first 270 argument (domain), it attempts to create a socket for HIP 271 communication. If HIP is not supported, socket() follows its default 272 behaviour and returns -1 and sets errno to EAFNOSUPPORT. 274 Figure 2 shows the recommended implementation of the socket address 275 structure for HIP in POSIX.1.g format. 277 #include 279 typedef struct in6_addr hip_hit_t; 281 struct sockaddr_hip { 282 uint8_t ship_len; 283 sa_family_t ship_family; 284 in_port_t ship_port; 285 uint32_t ship_flags; 286 ' hip_hit_t ship_hit; 287 }; 289 Figure 2 291 uint8_t ship_len: This field is optional in POSIX.1.g (and 4.3BSD- 292 RENO). The field defines the length of the structure. 293 Implementations that do not define this field typically embed the 294 information in the following ship_family field. 296 sa_family_t ship_family: This mandatory field identifies this as a 297 sockaddr_hip structure. It overlays the sa_family field of the 298 sockaddr structure. Its value must be AF_HIP. 300 in_port_t ship_port: This mandatory field contains the transport 301 protocol port number. It is handled in the same way as the sin_port 302 field of the sockaddr_in structure. The port number is stored in 303 network byte order. 305 uint32_t ship_flags: This mandatory bit field contains auxiliary 306 flags. This document does not define any flags. This field is 307 included for future extensions. 309 hip_hit_t ship_hit: This mandatory field contains the end-point 310 identifier. When the system passes a sockaddr_hip structure to the 311 application, the value of this field is set to a valid HIT, IPv4, or 312 IPv6 address, as discussed in Section 4.5. When the application 313 passes a sockaddr_hip structure to the system, this field must be set 314 to a HIT or a wildcard address as discussed in Section 4.1.1. 316 Some applications rely on system level access control, either 317 implicit or explicit (such as the accept_filter() function found on 318 BSD-based systems), but such discussion is out of scope. Other 319 applications implement access control themselves by using the HITs. 320 Applications operating on sockaddr_hip structures can use memcmp() or 321 similar function to compare the ship_hit fields. It should be also 322 noted that different connection attempts between the same two hosts 323 can result in different HITs because a host is allowed to have 324 multiple HITs. 326 4.1.1. HIP Wildcard Addresses 328 HIP wildcard addresses are similar to IPv4 and IPv6 wildcard 329 addresses. They can be used instead of specific HITs in the ship_hit 330 field for local and remote end-points in socket API calls such as 331 bind(), connect(), sendto(), sendmsg(). 333 In order to bind to all local IPv4 and IPv6 addresses and HIP HITs, 334 the ship_hit field must be set to HIP_ENDPOINT_ANY. In order to bind 335 to all local HITs, ship_hit must contain HIP_HIT_ANY. To only bind 336 to all local public HITs, the ship_hit field must be HIP_HIT_ANY_PUB. 337 The value HIP_HIT_ANY_TMP binds a socket to all local anonymous 338 identifiers only as specified in [RFC4423]. The system may label 339 anonymous identifiers as such depending on whether they have been 340 published or not. After binding a socket via one of the 341 HIP_HIT_ANY_* wildcard addresses, the application is guaranteed to 342 receive only HIP-based data flows. With the HIP_ENDPOINT_ANY 343 wildcard address, the socket accepts HIP, IPv6, and IPv4-based data 344 flows. 346 When a socket is bound or connected via a sockaddr_hip structure, 347 i.e. the PF_HIP protocol family, the system returns only addresses of 348 the AF_HIP family, i.e. sockaddr_hip structures, for this socket. 349 This applies to all functions which provide addresses to the 350 application, such as accept() or recvfrom(). If the data flow is 351 based on HIP, the ship_hit field contains the peer's HIT. For a non- 352 HIP IPv6 data flow, the field contains the peer's IPv6 address. For 353 a non-HIP IPv4 data flow, the field contains the peer's IPv4 address 354 in IPv4-mapped IPv6 address format as described in section 3.7 of 355 [RFC3493]. Section 4.5 describes how the application can verify the 356 type of the address returned by the socket API calls. 358 An application uses the socket API as follows to set up a connection 359 or to send messages in HIP Opportunistic Mode (cf. [RFC5201]). 360 First, the application associates a socket with at least one IP 361 address of the destination peer via setting the 362 SHIM_LOCLIST_PEER_PREF socket option. It then uses outgoing socket 363 functions such as connect(), sendto(), or sendmsg() with the 364 HIP_ENDPOINT_ANY or HIP_HIT_ANY wildcard address in the ship_hit 365 field of the sockaddr_hip structure. With the HIP_HIT_ANY address, 366 the underlying system allows only HIP-based data flows with the 367 corresponding socket. For incoming packets, the system discards all 368 non-HIP-related traffic arriving at the socket. For outgoing 369 packets, the system returns -1 in the socket call and sets errno to 370 an appropriate error type when the system failed to deliver the 371 packet over a HIP-based data channel. The semantics of using the 372 HIP_ENDPOINT_ANY are the subject of further experimentation in the 373 context of opportunistic mode. Such use may result in a data flow 374 either with or without HIP. 376 4.2. Extensions to Resolver Data Structures 378 The HIP APIs introduce a new address family, AF_HIP, that HIP-aware 379 applications can use to control the address type returned from the 380 getaddrinfo() function [RFC3493]. The getaddrinfo() function uses a 381 data structure called addrinfo in its "hints" and "res" argument 382 which is described in more detail in the next section. The addrinfo 383 data structure is illustrated in Figure 3. 385 #include 387 struct addrinfo { 388 int ai_flags; /* e.g. AI_CANONNAME */ 389 int ai_family; /* e.g. AF_HIP */ 390 int ai_socktype; /* e.g. SOCK_STREAM */ 391 int ai_protocol; /* 0 or IPPROTO_HIP */ 392 socklen_t ai_addrlen; /* size of *ai_addr */ 393 struct sockaddr *ai_addr; /* sockaddr_hip */ 394 char *ai_canonname; /* canon. name of the host */ 395 struct addrinfo *ai_next; /* next endpoint */ 396 int ai_eflags; /* RFC5014 extension */ 397 }; 399 Figure 3 401 An application resolving with the ai_family field set to AF_UNSPEC in 402 the hints argument may receive any kind of socket address structures, 403 including sockaddr_hip. When the application wants to receive only 404 HITs contained in sockaddr_hip structures, it should set the 405 ai_family field to AF_HIP. Otherwise, the resolver does not return 406 any sockaddr_hip structures. The resolver returns EAI_FAMILY when 407 AF_HIP is not supported. 409 The resolver ignores the AI_PASSIVE flag when the application sets 410 the family in hints to AF_HIP. 412 The system may have a HIP-aware interposing DNS agent as described in 413 section 3.2 in [RFC5338]. In such a case, the DNS agent may, 414 according to local policy, return transparently LSIs or HITs in 415 sockaddr_in and sockaddr_in6 structures when available. A HIP-aware 416 application can override this local policy in two ways. First, the 417 application can set the family to AF_HIP in the hints argument of 418 getaddrinfo() when it requests only sockaddr_hip structures. Second, 419 the application can set AI_NO_HIT flag to prevent the resolver from 420 returning HITs in any kind of data structures. 422 When getaddrinfo() returns resolved outputs in the output "res" 423 argument, it sets the family to AF_HIP when the related structure is 424 sockaddr_hip. 426 4.2.1. Resolver Usage 428 A HIP-aware application creates the sockaddr_hip structures manually 429 or obtains them from the resolver. The explicit configuration of 430 locators is described in [I-D.ietf-shim6-multihome-shim-api]. This 431 document defines "automated" resolver extensions for getaddrinfo() 432 resolver [RFC3493]. Other resolver calls, such as gethostbyname() 433 and getservbyname() are not defined in this document. The 434 getaddrinfo resolver interface is shown in Figure 4. 436 #include 438 int getaddrinfo(const char *nodename, 439 const char *servname, 440 const struct addrinfo *hints, 441 struct addrinfo **res) 442 void free_addrinfo(struct addrinfo *res) 444 Figure 4 446 As described in [RFC3493], the getaddrinfo() function takes the 447 nodename, servname, and hints as its input arguments. It places the 448 result of the query into the res output argument. The return value 449 is zero on success, or a non-zero error value on error. The nodename 450 argument specifies the host name to be resolved; a NULL argument 451 denotes the HITs of the local host. The servname parameter declares 452 the port number to be set in the socket addresses in the res output 453 argument. Both the nodename and servname cannot be NULL at the same 454 time. 456 The input argument "hints" acts like a filter that defines the 457 attributes required from the resolved endpoints. A NULL hints 458 argument indicates that any kind of endpoints are acceptable. 460 The output argument "res" is dynamically allocated by the resolver. 461 The application frees the res argument with the free_addrinfo 462 function. The res argument contains a linked list of the resolved 463 endpoints. The linked list contains only sockaddr_hip structures 464 when the input argument has the family set to AF_HIP. When the 465 family is zero, the list contains sockaddr_hip structures before 466 sockaddr_in and sockaddr_in6 structures. 468 The resolver can return a HIT which maps to multiple locators. The 469 resolver may cache the locator mappings with the HIP module. The HIP 470 module manages the multiple locators according to system policies of 471 the host. The multihoming document 472 [I-D.ietf-shim6-multihome-shim-api] describes how an application can 473 override system default policies. 475 It should be noted that the application can configure the HIT 476 explicitly without setting the locator or the resolver can fail to 477 resolve any locator. In this scenario, the application relies on the 478 system to map the HIT to an IP address. When the system fails to 479 provide the mapping, it returns -1 in the called sockets API function 480 to the application and sets errno to EADDRNOTAVAIL. 482 4.3. The Use of getsockname and getpeername Functions 484 The sockaddr_hip structure does not contain a HIT when the 485 application uses the HIP_HIT_ANY_* or HIP_ENDPOINT_ANY constants. In 486 such a case, the application can discover the local and peer HITs 487 using the getsockname() and getpeername() functions after the socket 488 is connected. The functions getsockname() and getpeername() always 489 output a sockaddr_hip structure when the family of the socket is 490 AF_HIP. The application should be prepared to handle also IPv4 and 491 IPv6 addresses in the ship_hit field as described in Section 4.1 in 492 the context of the HIP_ENDPOINT_ANY constant. 494 4.4. Selection of Source HIT Type 496 A client-side application can choose its source HIT by e.g. querying 497 all of the local HITs with getaddrinfo() and associating one of them 498 with the socket using bind(). This section describes another method 499 for a client-side application to affect the selection of the source 500 HIT type where the application does not call bind() explicitly. 501 Instead, the application just specifies the preferred requirements 502 for the source HIT type. 504 The Socket API for Source Address Selection [RFC5014] defines socket 505 options to allow applications to influence source address selection 506 mechanisms. In some cases, HIP-aware applications may want to 507 influence source HIT selection; in particular, whether an outbound 508 connection should use a published or anonymous HIT. Similar to 509 IPV6_ADDR_PREFERENCES defined in [RFC5014], the socket option 510 HIT_PREFERENCES is defined for HIP-based sockets. This socket option 511 can be used with setsockopt() and getsockopt() calls to set and get 512 the HIT selection preferences affecting a HIP-enabled socket. The 513 socket option value (optval) is a 32-bit unsigned integer argument. 514 The argument consists of a number of flags where each flag indicates 515 an address selection preference that modifies one of the rules in the 516 default HIT selection; these flags are shown in Table 2. 518 +---------------------------+-------------------------+ 519 | Socket Option | Purpose | 520 +---------------------------+-------------------------+ 521 | HIP_PREFER_SRC_HIT_TMP | Prefer an anonymous HIT | 522 | HIP_PREFER_SRC_HIT_PUBLIC | Prefer a public HIT | 523 +---------------------------+-------------------------+ 525 Table 2 527 If the system is unable to assign the type of HIT that is requested, 528 at HIT selection time, the socket call (connect(), sendto(), or 529 sendmsg()) will fail and errno will be set to EINVAL. If the 530 application tries to set both of the above flags for the same socket, 531 this also results in the error EINVAL. 533 4.5. Verification of HIT Type 535 An application that uses the HIP_ENDPOINT_ANY constant may want to 536 check whether the actual communications was based on HIP or not. 537 Also, the application may want to verify whether a HIT belonging to 538 the local host is public or anonymous. The application accomplishes 539 this using a new function called sockaddr_is_srcaddr() which is 540 illustrated in Figure 5. 542 #include 544 short sockaddr_is_srcaddr(struct sockaddr *srcaddr, 545 uint64_t flags); 547 Figure 5 549 The sockaddr_is_srcaddr() function operates in the same way as the 550 inet6_is_srcaddr() function [RFC5014] which can be used to verify the 551 type of an address belonging to the local host. The difference is 552 that the sockaddr_is_srcaddr() function handles sockaddr_hip 553 structures in addition to sockaddr_in6, and possibly other socket 554 structures in further extensions. Also, the length of the flags 555 argument is 64-bits instead of 32 bits because the new function 556 handles the same flags as defined in [RFC5014] in addition to two 557 HIP-specific flags, HIP_PREFER_SRC_HIT_TMP and 558 HIP_PREFER_SRC_HIT_PUBLIC. With these two flags, the application can 559 distinguish anonymous HITs from public HITs. 561 When given an AF_INET6 socket, sockaddr_is_srcaddr() behaves as 562 inet6_is_srcaddr() function as described in [RFC5014]. With an 563 AF_HIP socket, the function returns 1 when the HIT contained in the 564 socket address structure corresponds to a valid HIT of the local host 565 and the HIT satisfies the given flags. The function returns -1 when 566 the HIT does not belong to the local host or the flags are not valid. 567 The function returns 0 when the preference flags are valid but the 568 HIT does not match the given flags. The function also returns 0 on a 569 sockaddr_hip structure containing a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* 570 wildcard. 572 The sockaddr_is_srcaddr() interface applies only to local HITs. 573 Applications can call the function hip_is_hit() to verify that the 574 given hit_hit_t pointer has the HIT prefix. The function is 575 illustrated in Figure 6. 577 #include 579 short hip_is_hit(hip_hit_t *hit); 581 Figure 6 583 The hip_is_hit() function returns 1 when the given argument contains 584 the HIT prefix. The function returns -1 on error and sets errno 585 appropriately. The function returns 0 when the argument does not 586 have the HIT prefix. The function also returns 0 when the argument 587 is a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard. 589 4.6. Explicit Handling of Locators 591 The system resolver, or the HIP module, maps HITs to locators 592 implicitly. However, some applications may want to specify initial 593 locator mappings explicitly. In such a case, the application first 594 creates a socket with AF_HIP as the domain argument. Second, the 595 application may get or set locator information with one of the 596 following shim socket options as defined in the multihoming 597 extensions in [I-D.ietf-shim6-multihome-shim-api]. The related 598 socket options are summarized briefly in Table 3. 600 +---------------------+---------------------------------------------+ 601 | optname | description | 602 +---------------------+---------------------------------------------+ 603 | SHIM_LOC_LOCAL_PREF | Get or set the preferred locator on the | 604 | | local side for the context associated with | 605 | | the socket. | 606 | SHIM_LOC_PEER_PREF | Get or set the preferred locator on the | 607 | | remote side for the context associated with | 608 | | the socket. | 609 | SHIM_LOCLIST_LOCAL | Get or set a list of locators associated | 610 | | with the local EID. | 611 | SHIM_LOCLIST_PEER | Get or set a list of locators associated | 612 | | with the peer's EID. | 613 | SHIM_LOC_LOCAL_SEND | Set or get the default source locator of | 614 | | outgoing IP packets. | 615 | SHIM_LOC_PEER_SEND | Set or get the default destination locator | 616 | | of outgoing IP packets. | 617 +---------------------+---------------------------------------------+ 619 Table 3 621 As an example of locator mappings, a connection-oriented application 622 creates a HIP-based socket and sets the SHIM_LOCLIST_PEER socket 623 option on the socket. The HIP module uses the first address 624 contained in the option if multiple are provided. If the application 625 provides one or more addresses in the SHIM_LOCLIST_PEER setsockopt 626 call, the system should not connect to the host via another 627 destination address, in case the application intends to restrict the 628 range of addresses permissible as a policy choice. The application 629 can override the default peer locator by setting the 630 SHIM_LOC_PEER_PREF socket option if necessary. Finally, the 631 application provides a specific HIT in the ship_hit field of the 632 sockaddr_hip in the connect() system call. If the system cannot 633 reach the HIT at one of the addresses provided, the outbound socket 634 API functions (connect, sendmsg, etc.) return -1 and set errno to 635 EINVALIDLOCATOR. 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 Another use case is to use the opportunistic mode when the 642 destination HIT is specified as a wildcard. The application sets one 643 or more destination addresses using the SHIM_LOCLIST_PEER socket 644 option as described earlier in this section and then calls connect() 645 with the wildcard HIT. The connect() call returns -1 and sets errno 646 to EADDRNOTAVAIL when the application connects to a wildcard without 647 specifying any destination address. 649 Applications using datagram-oriented sockets can use ancillary data 650 to control the locators, as described in detail in 651 [I-D.ietf-shim6-multihome-shim-api]. 653 5. Summary of New Definitions 655 Table 4 summarizes the new constants and structures defined in this 656 document. 658 +-----------------+-----------------------+ 659 | Header | Definition | 660 +-----------------+-----------------------+ 661 | | AF_HIP | 662 | | PF_HIP | 663 | | IPPROTO_HIP | 664 | | HIP_HIT_ANY | 665 | | HIP_HIT_ANY_PUB | 666 | | HIP_HIT_ANY_TMP | 667 | | HIP_ENDPOINT_ANY | 668 | | HIP_HIT_PREFERENCES | 669 | | hip_hit_t | 670 | | AI_NO_HIT | 671 | | sockaddr_hip | 672 | | sockaddr_is_srcaddr() | 673 | | hip_is_hit() | 674 +-----------------+-----------------------+ 676 Table 4 678 6. IANA Considerations 680 No IANA considerations. 682 7. Security Considerations 684 The HIP_ENDPOINT_ANY constant can be used to accept incoming or 685 create outgoing data flows without HIP. The application should use 686 the sockaddr_is_srcaddr() function to validate the type of the 687 connection in order to e.g. inform the user of the lack of HIP-based 688 security. The use of the HIP_HIT_ANY_* constants is recommended in 689 security-critical applications and systems. 691 It should be noted that the wildcards described in this document are 692 not suitable for identifying end-hosts. Instead, applications should 693 use getsockname() and getpeername() as described in Section 4.3 to 694 identify an end-host. 696 Future proofing of HITs was discussed during the design of this API. 697 If HITs longer than 128-bits are required at the application layer, 698 this will require explicit support from the applications because they 699 can store or cache HITs with their explicit sizes. To support longer 700 HITs, further extensions of this API may define an additional flag 701 for getaddrinfo() to generate different kind of socket address 702 structures for HIP. 704 8. Contributors 706 Thanks for Jukka Ylitalo and Pekka Nikander for their original 707 contribution, time and effort to the native HIP APIs. Thanks for 708 Yoshifuji Hideaki and Stefan Goetz for their contributions to this 709 document. 711 9. Acknowledgements 713 Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan 714 Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti 715 Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keranen, 716 Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Joakim Koskela, 717 Jeff Ahrenholz, Tobias Heer, Stefan Gotz and Gonzalo Camarillo have 718 provided valuable ideas and feedback. Thanks also for the APPS area 719 folks, including Stephane Bortzmeyer, Chris Newman, Tony Finch, "der 720 Mouse" and Keith Moore. 722 10. Normative References 724 [I-D.ietf-btns-c-api] 725 Richardson, M., Williams, N., Komu, M., and S. Tarkoma, 726 "C-Bindings for IPsec Application Programming Interfaces", 727 draft-ietf-btns-c-api-04 (work in progress), March 2009. 729 [I-D.ietf-shim6-multihome-shim-api] 730 Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, 731 "Socket Application Program Interface (API) for 732 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-09 733 (work in progress), July 2009. 735 [I-D.ietf-shim6-proto] 736 Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 737 Shim Protocol for IPv6", draft-ietf-shim6-proto-12 (work 738 in progress), February 2009. 740 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 741 Std. 1003.1-2001 Standard for Information Technology - 742 Portable Operating System Interface (POSIX)", Dec 2001. 744 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 745 Stevens, "Basic Socket Interface Extensions for IPv6", 746 RFC 3493, February 2003. 748 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 749 (HIP) Architecture", RFC 4423, May 2006. 751 [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix 752 for Overlay Routable Cryptographic Hash Identifiers 753 (ORCHID)", RFC 4843, April 2007. 755 [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 756 Socket API for Source Address Selection", RFC 5014, 757 September 2007. 759 [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, 760 "Host Identity Protocol", RFC 5201, April 2008. 762 [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol 763 (HIP) Domain Name System (DNS) Extensions", RFC 5205, 764 April 2008. 766 [RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host 767 Identity Protocol with Legacy Applications", RFC 5338, 768 September 2008. 770 Authors' Addresses 772 Miika Komu 773 Helsinki Institute for Information Technology 774 Metsanneidonkuja 4 775 Helsinki 776 Finland 778 Phone: +358503841531 779 Fax: +35896949768 780 Email: miika@iki.fi 781 URI: http://www.iki.fi/miika/ 783 Thomas Henderson 784 The Boeing Company 785 P.O. Box 3707 786 Seattle, WA 787 USA 789 Email: thomas.r.henderson@boeing.com