idnits 2.17.1 draft-ietf-hip-native-api-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 421 has weird spacing: '... struct soc...' == Line 423 has weird spacing: '... struct add...' -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 11, 2010) is 5217 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-12 ** 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 (~~), 4 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: July 15, 2010 T. Henderson 6 The Boeing Company 7 January 11, 2010 9 Basic Socket Interface Extensions for Host Identity Protocol (HIP) 10 draft-ietf-hip-native-api-12 12 Abstract 14 This document defines extensions to the current sockets API for the 15 Host Identity Protocol (HIP). The extensions focus on the use of 16 public-key based identifiers discovered via DNS resolution, but 17 define also interfaces for manual bindings between HITs and locators. 18 With the extensions, the application can also support more relaxed 19 security models where the communication can be non-HIP based, 20 according to local policies. The extensions in this document are 21 experimental and provide basic tools for further experimentation with 22 policies. 24 Status of this Memo 26 This Internet-Draft is submitted to IETF in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as Internet- 32 Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/ietf/1id-abstracts.txt. 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html. 45 This Internet-Draft will expire on July 15, 2010. 47 Copyright Notice 48 Copyright (c) 2010 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the BSD License. 61 This document may contain material from IETF Documents or IETF 62 Contributions published or made publicly available before November 63 10, 2008. The person(s) controlling the copyright in some of this 64 material may not have granted the IETF Trust the right to allow 65 modifications of such material outside the IETF Standards Process. 66 Without obtaining an adequate license from the person(s) controlling 67 the copyright in such materials, this document may not be modified 68 outside the IETF Standards Process, and derivative works of it may 69 not be created outside the IETF Standards Process, except to format 70 it for publication as an RFC or to translate it into languages other 71 than English. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 76 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 77 3. Name Resolution Process . . . . . . . . . . . . . . . . . . . 6 78 3.1. Interaction with the Resolver . . . . . . . . . . . . . . 6 79 3.2. Interaction without a Resolver . . . . . . . . . . . . . . 7 80 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 8 81 4.1. Socket Family and Address Structure Extensions . . . . . . 8 82 4.2. Extensions to Resolver Data Structures . . . . . . . . . . 10 83 4.3. The Use of getsockname and getpeername Functions . . . . . 12 84 4.4. Selection of Source HIT Type . . . . . . . . . . . . . . . 13 85 4.5. Verification of HIT Type . . . . . . . . . . . . . . . . . 13 86 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 15 87 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 16 88 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 89 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 90 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 17 91 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 92 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 93 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 94 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 97 1. Introduction 99 This document defines the C-based sockets Application Programming 100 Interface (API) extensions for handling Host Identity Protocol (HIP)- 101 based identifiers explicitly in HIP-aware applications. It is up to 102 the applications, or high-level programming languages or libraries, 103 to manage the identifiers. The extensions in this document are 104 mainly related to the use case in which a DNS resolution step has 105 occurred prior to the creation of a new socket, and assumes that the 106 system has cached or is otherwise able to resolve identifiers to 107 locators (IP addresses). The DNS extensions for HIP are described in 108 [RFC5205]. The extensions also cover the case in which an 109 application may want to explicitly provide suggested locators with 110 the identifiers, including supporting the opportunistic case in which 111 the system does not know the peer host identity. 113 The Host Identity Protocol (HIP) [RFC4423] proposes a new 114 cryptographic namespace by separating the roles of end-point 115 identifiers and locators by introducing a new namespace to the TCP/IP 116 stack. SHIM6 [RFC5533] is another protocol based on an identity- 117 locator split. The APIs specified in this document are specific to 118 HIP, but have been designed as much as possible so as not to preclude 119 its use with other protocols. The use of these APIs with other 120 protocols is, nevertheless, for further study. 122 The APIs in this document are based on HITs that are defined as IPv6 123 addresses with the Overlay Routable Cryptographic Host Identifiers 124 (ORCHID) prefix [RFC4843]. ORCHIDs are derived from Host Identifiers 125 using a hash and fitting the result into an IPv6 address. Such 126 addresses are called Host Identity Tags (HITs) and they can be 127 distinguished from other IPv6 addresses via the ORCHID prefix. Note 128 that ORCHIDs are presently an experimental allocation by IANA. If 129 the ORCHID allocation were to expire and HIT generation were to use a 130 different prefix in the future, most users of the API would not be 131 impacted, unless they explicitly checked the ORCHID prefix on 132 returned HITs. Users who check (for consistency) that HITs have a 133 valid ORCHID prefix must monitor the IANA allocation for ORCHIDs and 134 adapt their software in case the ORCHID allocation were to be removed 135 at a future date. 137 Applications can observe the HIP layer and its identifiers in the 138 networking stacks with varying degrees of visibility. [RFC5338] 139 discusses the lowest levels of visibility in which applications are 140 completely unaware of the underlying HIP layer. Such HIP-unaware 141 applications in some circumstances use HIP-based identifiers, such as 142 Local Scope Identifiers (LSIs) or HITs, instead of IPv4 or IPv6 143 addresses and cannot observe the identifier-locator bindings. 145 This document specifies extensions to [RFC3493] to define a new 146 socket address family, AF_HIP. Similarly to other address families, 147 AF_HIP can be used as an alias for PF_HIP. The extensions also 148 describe a new socket address structure for sockets using HITs 149 explicitly and describe how the socket calls in [RFC3493] are adapted 150 or extended as a result. 152 Some applications may accept incoming communications from any 153 identifier. Other applications may initiate outgoing communications 154 without the knowledge of the peer identifier in Opportunistic Mode 155 (section 4.1.6 in [RFC5201]) by just relying on a peer locator. This 156 document describes how to address both situations using "wildcards" 157 as described in Section 4.1.1. 159 This document references one additional API document that handles 160 multihoming and explicit-locator handling, defined in 161 [I-D.ietf-shim6-multihome-shim-api]. Most of the extensions defined 162 in this document can be used independently of the above document. 164 The identity-locator split introduced by HIP introduces some policy 165 related challenges with datagram oriented sockets, opportunistic 166 mode, and manual bindings between HITs and locators. The extensions 167 in this document are of an experimental nature and provide basic 168 tools for experimenting with policies. Policy related issues are 169 left for further experimentation. 171 To recap, the extensions in this document have three goals. The 172 first goal is to allow HIP-aware applications to open sockets to 173 other hosts based on the HITs alone, presuming that the underlying 174 system can resolve the HITs to addresses used for initial contact. 175 The second goal is that applications can explicitly initiate 176 communications with unknown peer identifiers. The third goal is to 177 illustrate how HIP-aware applications can use the SHIM API 178 [I-D.ietf-shim6-multihome-shim-api] to manually map locators to HITs. 180 This document was published as experimental because a number of its 181 normative references had experimental status. The success of this 182 experiment can be evaluated by a thorough implementation of the APIs 183 defined. 185 2. Terminology 187 The terms used in this document are summarized in Table 1. 189 +---------+---------------------------------------------------------+ 190 | Term | Explanation | 191 +---------+---------------------------------------------------------+ 192 | FQDN | Fully Qualified Domain Name | 193 | HIP | Host Identity Protocol | 194 | HI | Host Identity | 195 | HIT | Host Identity Tag, a 100-bit hash of a public key with | 196 | | a 28 bit prefix | 197 | LSI | Local Scope Identifier, a local, 32-bit descriptor for | 198 | | a given public key. | 199 | Locator | Routable IPv4 or IPv6 address used at the lower layers | 200 | RR | Return Routability | 201 +---------+---------------------------------------------------------+ 203 Table 1 205 3. Name Resolution Process 207 This section provides an overview of how the API can be used. First, 208 the case in which a resolver is involved in name resolution is 209 described, and then the case in which no resolver is involved is 210 described. 212 3.1. Interaction with the Resolver 214 Before an application can establish network communications with the 215 entity named by a given FQDN or relative host name, the application 216 must translate the name into the corresponding identifier(s). DNS- 217 based hostname-to-identifier translation is illustrated in Figure 1. 218 The application calls the resolver in step (a) to resolve an FQDN to 219 one or more socket addresses within the PF_HIP family. The resolver, 220 in turn, queries the DNS in step (b) to map the FQDN to one or more 221 HIP RRs with the HIT and HI and possibly rendezvous server of the 222 Responder, and also (in parallel or sequentially) to resolve the FQDN 223 into possibly one or more A and AAAA records. It should be noted 224 that the FQDN may map to multiple host identifiers and locators, and 225 this step may involve multiple DNS transactions, including queries 226 for A, AAAA, HI and possibly other resource records. The DNS server 227 responds with a list of HIP resource records in step (c). Optionally 228 in step (d), the resolver caches the HIT-to-locator mapping with the 229 HIP module. The resolver converts the HIP records to HITs and 230 returns the HITs to the application contained in HIP socket address 231 structures in step (e). Depending on the parameters for the resolver 232 call, the resolver may return also other socket address structures to 233 the application. Finally, the application receives the socket 234 address structure(s) from the resolver and uses them in socket calls 235 such as connect() in step (f). 237 +----------+ 238 | | 239 | DNS | 240 | | 241 +----------+ 242 ^ | 243 b. QNAME=FQDN | | c. HIP and 244 | | A/AAAA 245 | v RR(s) 246 +-------------+ a. getaddrinfo() +----------+ 247 | |------------------------>| | 248 | Application | | Resolver | 249 | |<------------------------| | 250 +-------------+ e. +----------+ 251 | | 252 | | d. HIP and 253 | f. connect() | A/AAAA 254 | or any other socket call | RR(s) 255 v v 256 +----------+ +----------+ 257 | | | | 258 | TCP/IP | | HIP | 259 | Stack | | | 260 +----------+ +----------+ 262 Figure 1 264 In practice, the resolver functionality can be implemented in 265 different ways. For example, it may be implemented in existing 266 resolver libraries or as a HIP-aware interposing agent. 268 3.2. Interaction without a Resolver 270 The extensions in this document focus on the use of the resolver to 271 map host names to HITs and locators in HIP-aware applications. The 272 resolver may implicitly associate a HIT with the corresponding 273 locator(s) by communicating the HIT-to-IP mapping to the HIP daemon. 274 However, it is possible that an application operates directly on a 275 peer HIT without interacting with the resolver. In such a case, the 276 application may resort to the system to map the peer HIT to an IP 277 address. Alternatively, the application can explicitly map the HIT 278 to an IP address using socket options as specified in Section 4.6. 279 Full support for all of the extensions defined in this draft requires 280 a number of shim socket options [I-D.ietf-shim6-multihome-shim-api] 281 to be implemented by the system. 283 4. API Syntax and Semantics 285 In this section, we describe the native HIP APIs using the syntax of 286 the C programming language. We limit the description to the 287 interfaces and data structures that are either modified or completely 288 new because the native HIP APIs are otherwise identical to the 289 sockets API [POSIX]. 291 4.1. Socket Family and Address Structure Extensions 293 The sockets API extensions define a new protocol family, PF_HIP, and 294 a new address family, AF_HIP. The AF_HIP and PF_HIP constants are 295 aliases to each other. These definitions shall be defined as a 296 result of including . 298 When the socket() function is called with PF_HIP as the first 299 argument (domain), it attempts to create a socket for HIP 300 communication. If HIP is not supported, socket() follows its default 301 behaviour and returns -1 and sets errno to EAFNOSUPPORT. 303 Figure 2 shows the recommended implementation of the socket address 304 structure for HIP in POSIX format. 306 #include 308 typedef struct in6_addr hip_hit_t; 310 struct sockaddr_hip { 311 uint8_t ship_len; 312 sa_family_t ship_family; 313 in_port_t ship_port; 314 uint32_t ship_flags; 315 hip_hit_t ship_hit; 316 }; 318 Figure 2 320 uint8_t ship_len: This field defines the length of the structure. 321 Implementations that do not define this field typically embed the 322 information in the following ship_family field. 324 sa_family_t ship_family: This mandatory field identifies this as a 325 sockaddr_hip structure. It overlays the sa_family field of the 326 sockaddr structure. Its value must be AF_HIP. 328 in_port_t ship_port: This mandatory field contains the transport 329 protocol port number. It is handled in the same way as the sin_port 330 field of the sockaddr_in structure. The port number is stored in 331 network byte order. 333 uint32_t ship_flags: This mandatory bit field contains auxiliary 334 flags. This document does not define any flags. This field is 335 included for future extensions. 337 hip_hit_t ship_hit: This mandatory field contains the end-point 338 identifier. When the system passes a sockaddr_hip structure to the 339 application, the value of this field is set to a valid HIT, IPv4, or 340 IPv6 address, as discussed in Section 4.5. When the application 341 passes a sockaddr_hip structure to the system, this field must be set 342 to a HIT or a wildcard address as discussed in Section 4.1.1. 344 Some applications rely on system level access control, either 345 implicit or explicit (such as the accept_filter() function found on 346 BSD-based systems), but such discussion is out of scope. Other 347 applications implement access control themselves by using the HITs. 348 Applications operating on sockaddr_hip structures can use memcmp() or 349 similar function to compare the ship_hit fields. It should be also 350 noted that different connection attempts between the same two hosts 351 can result in different HITs because a host is allowed to have 352 multiple HITs. 354 4.1.1. HIP Wildcard Addresses 356 HIP wildcard addresses are similar to IPv4 and IPv6 wildcard 357 addresses. They can be used instead of specific HITs in the ship_hit 358 field for local and remote end-points in socket API calls such as 359 bind(), connect(), sendto(), sendmsg(). 361 In order to bind to all local IPv4 and IPv6 addresses and HIP HITs, 362 the ship_hit field must be set to HIP_ENDPOINT_ANY. In order to bind 363 to all local HITs, ship_hit must contain HIP_HIT_ANY. To only bind 364 to all local public HITs, the ship_hit field must be HIP_HIT_ANY_PUB. 365 The value HIP_HIT_ANY_TMP binds a socket to all local anonymous 366 identifiers only as specified in [RFC4423]. The system may label 367 anonymous identifiers as such depending on whether they have been 368 published or not. After binding a socket via one of the 369 HIP_HIT_ANY_* wildcard addresses, the application is guaranteed to 370 receive only HIP-based data flows. With the HIP_ENDPOINT_ANY 371 wildcard address, the socket accepts HIP, IPv6, and IPv4-based data 372 flows. 374 When a socket is bound or connected via a sockaddr_hip structure, 375 i.e. the PF_HIP protocol family, the system returns only addresses of 376 the AF_HIP family, i.e. sockaddr_hip structures, for this socket. 377 This applies to all functions which provide addresses to the 378 application, such as accept() or recvfrom(). If the data flow is 379 based on HIP, the ship_hit field contains the peer's HIT. For a non- 380 HIP IPv6 data flow, the field contains the peer's IPv6 address. For 381 a non-HIP IPv4 data flow, the field contains the peer's IPv4 address 382 in IPv4-mapped IPv6 address format as described in section 3.7 of 383 [RFC3493]. Section 4.5 describes how the application can verify the 384 type of the address returned by the socket API calls. 386 An application uses the socket API as follows to set up a connection 387 or to send messages in HIP Opportunistic Mode (cf. [RFC5201]). 388 First, the application associates a socket with at least one IP 389 address of the destination peer via setting the 390 SHIM_LOCLIST_PEER_PREF socket option. It then uses outgoing socket 391 functions such as connect(), sendto(), or sendmsg() with the 392 HIP_ENDPOINT_ANY or HIP_HIT_ANY wildcard address in the ship_hit 393 field of the sockaddr_hip structure. With the HIP_HIT_ANY address, 394 the underlying system allows only HIP-based data flows with the 395 corresponding socket. For incoming packets, the system discards all 396 non-HIP-related traffic arriving at the socket. For outgoing 397 packets, the system returns -1 in the socket call and sets errno to 398 an appropriate error type when the system failed to deliver the 399 packet over a HIP-based data channel. The semantics of using the 400 HIP_ENDPOINT_ANY are the subject of further experimentation in the 401 context of opportunistic mode. Such use may result in a data flow 402 either with or without HIP. 404 4.2. Extensions to Resolver Data Structures 406 The HIP APIs introduce a new address family, AF_HIP, that HIP-aware 407 applications can use to control the address type returned from the 408 getaddrinfo() function [RFC3493], [POSIX]. The getaddrinfo() 409 function uses a data structure called addrinfo in its "hints" and 410 "res" argument which is described in more detail in the next section. 411 The addrinfo data structure is illustrated in Figure 3. 413 #include 415 struct addrinfo { 416 int ai_flags; /* e.g. AI_CANONNAME */ 417 int ai_family; /* e.g. AF_HIP */ 418 int ai_socktype; /* e.g. SOCK_STREAM */ 419 int ai_protocol; /* 0 or IPPROTO_HIP */ 420 socklen_t ai_addrlen; /* size of *ai_addr */ 421 struct sockaddr *ai_addr; /* sockaddr_hip */ 422 char *ai_canonname; /* canon. name of the host */ 423 struct addrinfo *ai_next; /* next endpoint */ 424 int ai_eflags; /* RFC5014 extension */ 425 }; 426 Figure 3 428 An application resolving with the ai_family field set to AF_UNSPEC in 429 the hints argument may receive any kind of socket address structures, 430 including sockaddr_hip. When the application wants to receive only 431 HITs contained in sockaddr_hip structures, it should set the 432 ai_family field to AF_HIP. Otherwise, the resolver does not return 433 any sockaddr_hip structures. The resolver returns EAI_FAMILY when 434 AF_HIP is requested but not supported. 436 The resolver ignores the AI_PASSIVE flag when the application sets 437 the family in hints to AF_HIP. 439 The system may have a HIP-aware interposing DNS agent as described in 440 section 3.2 in [RFC5338]. In such a case, the DNS agent may, 441 according to local policy, return transparently LSIs or HITs in 442 sockaddr_in and sockaddr_in6 structures when available. A HIP-aware 443 application can override this local policy in two ways. First, the 444 application can set the family to AF_HIP in the hints argument of 445 getaddrinfo() when it requests only sockaddr_hip structures. Second, 446 the application can set AI_NO_HIT flag to prevent the resolver from 447 returning HITs in any kind of data structures. 449 When getaddrinfo() returns resolved outputs in the output "res" 450 argument, it sets the family to AF_HIP when the related structure is 451 sockaddr_hip. 453 4.2.1. Resolver Usage 455 A HIP-aware application creates the sockaddr_hip structures manually 456 or obtains them from the resolver. The explicit configuration of 457 locators is described in [I-D.ietf-shim6-multihome-shim-api]. This 458 document defines "automated" resolver extensions for getaddrinfo() 459 resolver [RFC3493]. Other resolver calls, such as gethostbyname() 460 and getservbyname() are not defined in this document. The 461 getaddrinfo resolver interface is shown in Figure 4. 463 #include 465 int getaddrinfo(const char *nodename, 466 const char *servname, 467 const struct addrinfo *hints, 468 struct addrinfo **res) 469 void free_addrinfo(struct addrinfo *res) 471 Figure 4 473 As described in [RFC3493], the getaddrinfo() function takes the 474 nodename, servname, and hints as its input arguments. It places the 475 result of the query into the res output argument. The return value 476 is zero on success, or a non-zero error value on error. The nodename 477 argument specifies the host name to be resolved; a NULL argument 478 denotes the HITs of the local host. The servname parameter declares 479 the port number to be set in the socket addresses in the res output 480 argument. Both the nodename and servname cannot be NULL at the same 481 time. 483 The input argument "hints" acts like a filter that defines the 484 attributes required from the resolved endpoints. A NULL hints 485 argument indicates that any kind of endpoints are acceptable. 487 The output argument "res" is dynamically allocated by the resolver. 488 The application frees the res argument with the free_addrinfo 489 function. The res argument contains a linked list of the resolved 490 endpoints. The linked list contains only sockaddr_hip structures 491 when the input argument has the family set to AF_HIP. When the 492 family is zero, the list contains sockaddr_hip structures before 493 sockaddr_in and sockaddr_in6 structures. 495 The resolver can return a HIT which maps to multiple locators. The 496 resolver may cache the locator mappings with the HIP module. The HIP 497 module manages the multiple locators according to system policies of 498 the host. The multihoming document 499 [I-D.ietf-shim6-multihome-shim-api] describes how an application can 500 override system default policies. 502 It should be noted that the application can configure the HIT 503 explicitly without setting the locator or the resolver can fail to 504 resolve any locator. In this scenario, the application relies on the 505 system to map the HIT to an IP address. When the system fails to 506 provide the mapping, it returns -1 in the called sockets API function 507 to the application and sets errno to EADDRNOTAVAIL. 509 4.3. The Use of getsockname and getpeername Functions 511 The sockaddr_hip structure does not contain a HIT when the 512 application uses the HIP_HIT_ANY_* or HIP_ENDPOINT_ANY constants. In 513 such a case, the application can discover the local and peer HITs 514 using the getsockname() and getpeername() functions after the socket 515 is connected. The functions getsockname() and getpeername() always 516 output a sockaddr_hip structure when the family of the socket is 517 AF_HIP. The application should be prepared to handle also IPv4 and 518 IPv6 addresses in the ship_hit field as described in Section 4.1 in 519 the context of the HIP_ENDPOINT_ANY constant. 521 4.4. Selection of Source HIT Type 523 A client-side application can choose its source HIT by e.g. querying 524 all of the local HITs with getaddrinfo() and associating one of them 525 with the socket using bind(). This section describes another method 526 for a client-side application to affect the selection of the source 527 HIT type where the application does not call bind() explicitly. 528 Instead, the application just specifies the preferred requirements 529 for the source HIT type. 531 The Socket API for Source Address Selection [RFC5014] defines socket 532 options to allow applications to influence source address selection 533 mechanisms. In some cases, HIP-aware applications may want to 534 influence source HIT selection; in particular, whether an outbound 535 connection should use a published or anonymous HIT. Similar to 536 IPV6_ADDR_PREFERENCES defined in [RFC5014], the socket option 537 HIT_PREFERENCES is defined for HIP-based sockets. This socket option 538 can be used with setsockopt() and getsockopt() calls to set and get 539 the HIT selection preferences affecting a HIP-enabled socket. The 540 socket option value (optval) is a 32-bit unsigned integer argument. 541 The argument consists of a number of flags where each flag indicates 542 an address selection preference that modifies one of the rules in the 543 default HIT selection; these flags are shown in Table 2. 545 +---------------------------+-------------------------+ 546 | Socket Option | Purpose | 547 +---------------------------+-------------------------+ 548 | HIP_PREFER_SRC_HIT_TMP | Prefer an anonymous HIT | 549 | HIP_PREFER_SRC_HIT_PUBLIC | Prefer a public HIT | 550 +---------------------------+-------------------------+ 552 Table 2 554 If the system is unable to assign the type of HIT that is requested, 555 at HIT selection time, the socket call (connect(), sendto(), or 556 sendmsg()) will fail and errno will be set to EINVAL. If the 557 application tries to set both of the above flags for the same socket, 558 this also results in the error EINVAL. 560 4.5. Verification of HIT Type 562 An application that uses the HIP_ENDPOINT_ANY constant may want to 563 check whether the actual communications was based on HIP or not. 564 Also, the application may want to verify whether a HIT belonging to 565 the local host is public or anonymous. The application accomplishes 566 this using a new function called sockaddr_is_srcaddr() which is 567 illustrated in Figure 5. 569 #include 571 short sockaddr_is_srcaddr(struct sockaddr *srcaddr, 572 uint64_t flags); 574 Figure 5 576 The sockaddr_is_srcaddr() function operates in the same way as the 577 inet6_is_srcaddr() function [RFC5014] which can be used to verify the 578 type of an address belonging to the local host. The difference is 579 that the sockaddr_is_srcaddr() function handles sockaddr_hip 580 structures in addition to sockaddr_in6, and possibly other socket 581 structures in further extensions. Also, the length of the flags 582 argument is 64-bits instead of 32 bits because the new function 583 handles the same flags as defined in [RFC5014] in addition to two 584 HIP-specific flags, HIP_PREFER_SRC_HIT_TMP and 585 HIP_PREFER_SRC_HIT_PUBLIC. With these two flags, the application can 586 distinguish anonymous HITs from public HITs. 588 When given an AF_INET6 socket, sockaddr_is_srcaddr() behaves as 589 inet6_is_srcaddr() function as described in [RFC5014]. With an 590 AF_HIP socket, the function returns 1 when the HIT contained in the 591 socket address structure corresponds to a valid HIT of the local host 592 and the HIT satisfies the given flags. The function returns -1 when 593 the HIT does not belong to the local host or the flags are not valid. 594 The function returns 0 when the preference flags are valid but the 595 HIT does not match the given flags. The function also returns 0 on a 596 sockaddr_hip structure containing a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* 597 wildcard. 599 The sockaddr_is_srcaddr() interface applies only to local HITs. 600 Applications can call the function hip_is_hit() to verify that the 601 given hit_hit_t pointer has the HIT prefix. The function is 602 illustrated in Figure 6. 604 #include 606 short hip_is_hit(hip_hit_t *hit); 608 Figure 6 610 The hip_is_hit() function returns 1 when the given argument contains 611 the HIT prefix. The function returns -1 on error and sets errno 612 appropriately. The function returns 0 when the argument does not 613 have the HIT prefix. The function also returns 0 when the argument 614 is a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard. 616 4.6. Explicit Handling of Locators 618 The system resolver, or the HIP module, maps HITs to locators 619 implicitly. However, some applications may want to specify initial 620 locator mappings explicitly. In such a case, the application first 621 creates a socket with AF_HIP as the domain argument. Second, the 622 application may get or set locator information with one of the 623 following shim socket options as defined in the multihoming 624 extensions in [I-D.ietf-shim6-multihome-shim-api]. The related 625 socket options are summarized briefly in Table 3. 627 +---------------------+---------------------------------------------+ 628 | optname | description | 629 +---------------------+---------------------------------------------+ 630 | SHIM_LOC_LOCAL_PREF | Get or set the preferred locator on the | 631 | | local side for the context associated with | 632 | | the socket. | 633 | SHIM_LOC_PEER_PREF | Get or set the preferred locator on the | 634 | | remote side for the context associated with | 635 | | the socket. | 636 | SHIM_LOCLIST_LOCAL | Get or set a list of locators associated | 637 | | with the local EID. | 638 | SHIM_LOCLIST_PEER | Get or set a list of locators associated | 639 | | with the peer's EID. | 640 | SHIM_LOC_LOCAL_SEND | Set or get the default source locator of | 641 | | outgoing IP packets. | 642 | SHIM_LOC_PEER_SEND | Set or get the default destination locator | 643 | | of outgoing IP packets. | 644 +---------------------+---------------------------------------------+ 646 Table 3 648 As an example of locator mappings, a connection-oriented application 649 creates a HIP-based socket and sets the SHIM_LOCLIST_PEER socket 650 option on the socket. The HIP module uses the first address 651 contained in the option if multiple are provided. If the application 652 provides one or more addresses in the SHIM_LOCLIST_PEER setsockopt 653 call, the system should not connect to the host via another 654 destination address, in case the application intends to restrict the 655 range of addresses permissible as a policy choice. The application 656 can override the default peer locator by setting the 657 SHIM_LOC_PEER_PREF socket option if necessary. Finally, the 658 application provides a specific HIT in the ship_hit field of the 659 sockaddr_hip in the connect() system call. If the system cannot 660 reach the HIT at one of the addresses provided, the outbound socket 661 API functions (connect, sendmsg, etc.) return -1 and set errno to 662 EINVALIDLOCATOR. 664 Applications may also choose to associate local addresses with 665 sockets. The procedures specified in 666 [I-D.ietf-shim6-multihome-shim-api] are followed in this case. 668 Another use case is to use the opportunistic mode when the 669 destination HIT is specified as a wildcard. The application sets one 670 or more destination addresses using the SHIM_LOCLIST_PEER socket 671 option as described earlier in this section and then calls connect() 672 with the wildcard HIT. The connect() call returns -1 and sets errno 673 to EADDRNOTAVAIL when the application connects to a wildcard without 674 specifying any destination address. 676 Applications using datagram-oriented sockets can use ancillary data 677 to control the locators, as described in detail in 678 [I-D.ietf-shim6-multihome-shim-api]. 680 5. Summary of New Definitions 682 Table 4 summarizes the new constants and structures defined in this 683 document. 685 +-----------------+-----------------------+ 686 | Header | Definition | 687 +-----------------+-----------------------+ 688 | | AF_HIP | 689 | | PF_HIP | 690 | | IPPROTO_HIP | 691 | | HIP_HIT_ANY | 692 | | HIP_HIT_ANY_PUB | 693 | | HIP_HIT_ANY_TMP | 694 | | HIP_ENDPOINT_ANY | 695 | | HIP_HIT_PREFERENCES | 696 | | hip_hit_t | 697 | | AI_NO_HIT | 698 | | sockaddr_hip | 699 | | sockaddr_is_srcaddr() | 700 | | hip_is_hit() | 701 +-----------------+-----------------------+ 703 Table 4 705 6. IANA Considerations 707 No IANA considerations. 709 7. Security Considerations 711 This document describes an API for HIP and therefore depends on the 712 mechanisms defined in the HIP protocol suite. Security concerns 713 associated with HIP itself are specified in [RFC4423], [RFC4843], 714 [RFC5201], [RFC5205], and [RFC5338]. 716 The HIP_ENDPOINT_ANY constant can be used to accept incoming or 717 create outgoing data flows without HIP. The application should use 718 the sockaddr_is_srcaddr() function to validate the type of the 719 connection in order to e.g. inform the user of the lack of HIP-based 720 security. The use of the HIP_HIT_ANY_* constants is recommended in 721 security-critical applications and systems. 723 It should be noted that the wildcards described in this document are 724 not suitable for identifying end-hosts. Instead, applications should 725 use getsockname() and getpeername() as described in Section 4.3 to 726 identify an end-host. 728 Future proofing of HITs was discussed during the design of this API. 729 If HITs longer than 128-bits are required at the application layer, 730 this will require explicit support from the applications because they 731 can store or cache HITs with their explicit sizes. To support longer 732 HITs, further extensions of this API may define an additional flag 733 for getaddrinfo() to generate different kind of socket address 734 structures for HIP. 736 8. Contributors 738 Thanks for Jukka Ylitalo and Pekka Nikander for their original 739 contribution, time and effort to the native HIP APIs. Thanks for 740 Yoshifuji Hideaki and Stefan Goetz for their contributions to this 741 document. 743 9. Acknowledgements 745 Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan 746 Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti 747 Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keranen, 748 Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Joakim Koskela, 749 Jeff Ahrenholz, Tobias Heer and Gonzalo Camarillo have provided 750 valuable ideas and feedback. Thanks for Nick Stoughton from the 751 Austin group for POSIX-related comments. Thanks also for the APPS 752 area folks, including Stephane Bortzmeyer, Chris Newman, Tony Finch, 753 "der Mouse" and Keith Moore. 755 10. References 757 10.1. Normative References 759 [I-D.ietf-shim6-multihome-shim-api] 760 Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, 761 "Socket Application Program Interface (API) for 762 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-12 763 (work in progress), January 2010. 765 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 766 Std. 1003.1-2008 Standard for Information Technology - 767 Portable Operating System Interface (POSIX)", Dec 2001. 769 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 770 Stevens, "Basic Socket Interface Extensions for IPv6", 771 RFC 3493, February 2003. 773 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 774 (HIP) Architecture", RFC 4423, May 2006. 776 [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix 777 for Overlay Routable Cryptographic Hash Identifiers 778 (ORCHID)", RFC 4843, April 2007. 780 [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 781 Socket API for Source Address Selection", RFC 5014, 782 September 2007. 784 [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, 785 "Host Identity Protocol", RFC 5201, April 2008. 787 [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol 788 (HIP) Domain Name System (DNS) Extensions", RFC 5205, 789 April 2008. 791 [RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host 792 Identity Protocol with Legacy Applications", RFC 5338, 793 September 2008. 795 10.2. Informative References 797 [RFC5533] Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 798 Shim Protocol for IPv6", RFC 5533, June 2009. 800 Authors' Addresses 802 Miika Komu 803 Helsinki Institute for Information Technology 804 Metsanneidonkuja 4 805 Helsinki 806 Finland 808 Phone: +358503841531 809 Fax: +35896949768 810 Email: miika@iki.fi 811 URI: http://www.iki.fi/miika/ 813 Thomas Henderson 814 The Boeing Company 815 P.O. Box 3707 816 Seattle, WA 817 USA 819 Email: thomas.r.henderson@boeing.com