idnits 2.17.1 draft-mkomu-hip-native-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 17. -- Found old boilerplate from RFC 3978, Section 5.5 on line 712. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 689. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 696. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 702. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 15 longer pages, the longest (page 11) being 68 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 20 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 7 instances of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- 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 (Mar 2005) is 6975 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-10) exists of draft-ietf-hip-base-02 ** Downref: Normative reference to an Experimental draft: draft-ietf-hip-base (ref. 'I-D.ietf-hip-base') == Outdated reference: A later version (-05) exists of draft-ietf-hip-mm-01 ** Downref: Normative reference to an Experimental draft: draft-ietf-hip-mm (ref. 'I-D.ietf-hip-mm') -- Possible downref: Non-RFC (?) normative reference: ref. 'POSIX' ** Downref: Normative reference to an Informational RFC: RFC 3493 == Outdated reference: A later version (-03) exists of draft-henderson-hip-applications-00 Summary: 9 errors (**), 0 flaws (~~), 7 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Host Identity Protocol M. Komu 2 Internet-Draft Helsinki Institute for Information 3 Expires: August 30, 2005 Technology 4 Mar 2005 6 Native Application Programming Interfaces for the Host Identity 7 Protocol 8 draft-mkomu-hip-native-api-00.txt 10 Status of this Memo 12 This document is an Internet-Draft and is subject to all provisions 13 of section 3 of RFC 3667. By submitting this Internet-Draft, each 14 author represents that any applicable patent or other IPR claims of 15 which he or she is aware have been or will be disclosed, and any of 16 which he or she become aware will be disclosed, in accordance with 17 RFC 3668. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as 22 Internet-Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on August 30, 2005. 37 Copyright Notice 39 Copyright (C) The Internet Society (2005). 41 Abstract 43 This document proposes extensions to the current networking APIs. 44 Using the extented APIs, HIP aware applications can gain a better 45 control of the HIP layer and Host Identifiers. For example, the 46 applications can query and set security and mobility related 47 attributes, or specify their own Host Identifiers in a host. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Design Architecture . . . . . . . . . . . . . . . . . . . . . 4 54 2.1 Endpoint Descriptor . . . . . . . . . . . . . . . . . . . 4 55 2.2 Layering Model . . . . . . . . . . . . . . . . . . . . . . 4 56 2.3 Namespace Model . . . . . . . . . . . . . . . . . . . . . 4 57 2.4 Socket Bindings . . . . . . . . . . . . . . . . . . . . . 5 59 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 61 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 65 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 6.1 Normative References . . . . . . . . . . . . . . . . . . . . 11 67 6.2 Informative References . . . . . . . . . . . . . . . . . . . 11 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 11 71 A. Interface Syntax and Description . . . . . . . . . . . . . . . 12 72 A.1 Data Structures . . . . . . . . . . . . . . . . . . . . . 12 73 A.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . 14 74 A.2.1 Resolver Interface . . . . . . . . . . . . . . . . . . 15 75 A.2.2 Application Specified Identities . . . . . . . . . . . 15 76 A.2.3 Querying Endpoint Related Information . . . . . . . . 17 77 A.2.4 Socket Options . . . . . . . . . . . . . . . . . . . . 18 79 Intellectual Property and Copyright Statements . . . . . . . . 20 81 1. Introduction 83 Host Identity Protocol proposes a new cryptographic namespace and a 84 new layer to the TCP/IP architecture. Applications can see these new 85 changes in the networking stacks with varying degrees of visibility. 86 [I-D.henderson-hip-applications] discusses the lowest levels of 87 visibility in which applications are either completely or partially 88 unaware of HIP. In this document, we discuss about the highest level 89 of visibility. The applications are completely HIP aware and are 90 able to control the HIP layer and identifiers. The applications are 91 allowed to query and set security related attributes and even specify 92 their own Host Identifiers. 94 2. Design Architecture 96 In this section, the native HIP API design is described from an 97 architectural point of view. We introduce the ED concept, which is a 98 central idea in the API. We describe the layering and namespace 99 models along with the socket bindings. We conclude the discussion 100 with a description of the endpoint identifier resolution mechanism. 102 2.1 Endpoint Descriptor 104 The representation of endpoints is hidden from the applications. The 105 ED is a ``handle'' to a HI. A given ED serves as a pointer to the 106 corresponding HI entry in the HI database of the host. The ED is the 107 AID [I-D.nordmark-multi6-noid] in the native HIP API model. 109 2.2 Layering Model 111 The application layer accesses the transport layer via the socket 112 interface. The application layer uses the traditional TCP/IP IPv4 or 113 IPv6 interface, or the new native HIP API interface provided by the 114 socket layer. The layering model is illustrated in Figure 1. For 115 simplicity, the IPsec layer has been excluded from the figure. 117 +-------------------------------+ 118 Application Layer | Application | 119 +----------+----------+---------+ 120 Socket Layer | IPv4 API | IPv6 API | HIP API | 121 +----------+----+-----+---------+ 122 Transport Layer | TCP | UDP | 123 +---------------+---------------+ 124 HIP Layer | HIP | 125 +---------------+---------------+ 126 Network Layer | IPv4 | IPv6 | 127 +---------------+---------------+ 128 Link Layer | Ethernet | Etc | 129 +---------------+---------------+ 131 Figure 1 133 The HIP layer is as a shim/wedge layer between the transport and 134 network layers. The datagrams delivered between the transport and 135 network layers are intercepted in the HIP layer to see if the 136 datagrams are HIP related and require HIP intervention. 138 2.3 Namespace Model 140 The used namespace model is shown in . The namespace identifiers are 141 described in this section. 143 +-------------------+-----------------------+ 144 | Layer | Identifier | 145 +-------------------+-----------------------+ 146 | User Interface | FQDN | 147 | | | 148 | Application Layer | ED, port and protocol | 149 | | | 150 | Transport Layer | HI, port | 151 | | | 152 | HIP Layer | HI | 153 | | | 154 | Network Layer | IP address | 155 +-------------------+-----------------------+ 157 Table 1 159 People prefer human-readable names when referring to network 160 entities. The most commonly used identifier in the UI is the FQDN, 161 but there are also other ways to name network entities. The FQDN 162 format is still the preferred UI level identifier in the context of 163 the native HIP API. 165 In the current API, connection associations in the application layer 166 are uniquely distinguished by the source IP address, destination IP 167 address, source port, destination port, and protocol. HIP changes 168 this model by using HIT in the place of IP addresses. The HIP model 169 is further expanded in the native HIP API model by using ED instead 170 of HITs. Now, the application layer uses source ED, destination ED, 171 source port, destination port, and transport protocol type, to 172 distinguish between the different connection associations. 174 Basically, the difference between the application and transport layer 175 identifiers is that the transport layer uses HIs instead of EDs. The 176 TLI is named with source HI, destination HI, source port, and 177 destination port at the transport layer. 179 Correspondingly, the HIP layer uses HIs as identifiers. The HIP 180 security associations are based on source HI and destination HI 181 pairs. 183 The network layer uses IP addresses, i.e., locators, for routing 184 purposes. The network layer interacts with the HIP layer to exchange 185 information about changes in the local interfaces addresses and peer 186 addresses. 188 2.4 Socket Bindings 190 A HIP socket is associated with one source and one destination ED, 191 along with their port numbers and protocol type. The relationship 192 between a socket and ED is a many-to-one one. Multiple EDs can be 193 associated with a single HI. Further, the source HI is associated 194 with a set of network interfaces at the local host. The destination 195 HI, in turn, is associated with a set of destination addresses of the 196 peer. The socket bindings are visualized in Figure 2. 198 1 +---------+ * 1 +--------+ * 1 +-----------+ 199 +---+ Src EID +------+ Src HI +------+ Src Iface | 200 +--------+ * | +---------+ * 1 +--------+ +-----------+ 201 | HIP +------+ 202 | | 203 | Socket +------+ 204 +--------+ * | +---------+ * 1 +--------+ * 1 +-----------+ 205 +---+ Dst EID +------+ Dst HI +------+ Dst IP | 206 1 +---------+ * 1 +--------+ +-----------+ 208 Figure 2 210 The relationship between a source ED and a source HI is always a 211 many-to-one one. However, there are two refinements to the 212 relationship. First, a listening socket is allowed to accept 213 connections from all local HIs of the host. Second, the 214 opportunistic mode allows the base exchange to be initiated to an 215 unknown destination HI. In a way, the relationship between the local 216 ED and local HI is a many-to-undefined relationship for a moment in 217 both of the cases, but once the connection is established, the ED 218 will be permanently associated with a certain HI. 220 The ED concept can only be used in HIP protocol family sockets. 221 Other types of sockets are left intact to avoid breaking the 222 backwards compatibility. 224 The DNS based endpoint discovery mechanism is illustrated in . The 225 application calls the resolver (step a.) to resolve an FQDN (step 226 b.). The DNS server responds with a HI and a set of IP addresses 227 (step c.). The resolver does not directly pass the HI and the 228 locators to the application, but sends them to the HIP module (step 229 d.). Finally, the resolver receives an ED from the HIP module (step 230 e.) and passes the ED to the application (step f.). 232 +----------+ 233 | | 234 | DNS | 235 | | 236 +----------+ 237 ^ | 238 b. | | c. 239 | v 240 +-------------+ a. +----------+ 241 | |----------->| | 242 | Application | | Resolver | 243 | |<-----------| | 244 +-------------+ f. +----------+ 245 ^ | 246 e. | | d. 247 | v 248 +----------+ 249 | | 250 | HIP | 251 | | 252 +----------+ 254 Figure 3 256 The application can also receive multiple EDs from the resolver if 257 the FQDN is associated with multiple HIs. The endpoint discovery 258 mechanism is still almost the same. The difference is that the DNS 259 returns a set of HIs (along with their locators) to the resolver. 260 The resolver sends all of them to the HIP module and receives a set 261 of EDs in return, each ED corresponding to a single HI. Finally, the 262 EDs are sent to the application. 264 3. IANA Considerations 266 To be done. 268 4. Security Considerations 270 To be done. 272 5. Acknowledgements 274 Jukka Ylitalo and Pekka Nikander have contributed many ideas, time 275 and effort to the native HIP API. Thomas Henderson, Kristian Slavov, 276 Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew 277 McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti J?rvinen and 278 Anthony Joseph have also provided valuable ideas and feedback. 280 6. References 282 6.1 Normative References 284 [I-D.ietf-hip-base] 285 Moskowitz, R., "Host Identity Protocol", 286 draft-ietf-hip-base-02 (work in progress), February 2005. 288 [I-D.ietf-hip-mm] 289 Nikander, P., "End-Host Mobility and Multi-Homing with 290 Host Identity Protocol", draft-ietf-hip-mm-01 (work in 291 progress), February 2005. 293 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 294 Std. 1003.1-2001 Standard for Information Technology - 295 Portable Operating System Interface (POSIX)", Dec 2001. 297 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J. and W. 298 Stevens, "Basic Socket Interface Extensions for IPv6", RFC 299 3493, February 2003. 301 6.2 Informative References 303 [I-D.henderson-hip-applications] 304 Henderson, T., "Using HIP with Legacy Applications", 305 draft-henderson-hip-applications-00 (work in progress), 306 February 2005. 308 [I-D.nordmark-multi6-noid] 309 Nordmark, E., "Multihoming without IP Identifiers", 310 draft-nordmark-multi6-noid-02 (work in progress), July 311 2004. 313 Author's Address 315 Miika Komu 316 Helsinki Institute for Information Technology 317 Tammasaarenkatu 3 318 Helsinki 319 Finland 321 Phone: +358503841531 322 Fax: +35896949768 323 EMail: miika@iki.fi 324 URI: http://www.iki.fi/miika/ 326 Appendix A. Interface Syntax and Description 328 In this section, we describe the native HIP API using the syntax of 329 the C programming language and present only the ``external'' 330 interfaces and data structures that are visible to the applications. 331 We limit the description to those interfaces and data structures that 332 are either modified or completely new, because the native HIP API is 333 otherwise identical to the sockets API [POSIX]. 335 A.1 Data Structures 337 We introduce a new protocol family, PF_HIP, for the sockets API. The 338 AF_HIP constant is an alias for it. The use of the PF_HIP constant 339 is mandatory with the socket function if the native HIP API is to be 340 used in the application. The PF_HIP constant is given as the first 341 argument (domain) to the socket function. 343 The ED abstraction is realized in the sockaddr_ed structure, which is 344 shown in figure Figure 4. The family of the socket, ed_family, is 345 set to PF_HIP. The port number ed_port is two octets and the ED 346 value ed_val is four octets. The ED value is just an opaque number 347 to the application. The application should not try to associate it 348 directly to a HI or even compare it to other ED values, because there 349 are separate functions for those purposes. The ED family is stored 350 in host byte order. The port and the ED value are stored in network 351 byte order. 353 struct sockaddr_ed { 354 unsigned short int ed_family; 355 in_port_t ed_port; 356 sa_ed_t ed_val; 357 } 359 Figure 4 361 The ed_val field is usually set by special native HIP API functions, 362 which are described in the following section. However, three special 363 macros can be used to directly set a value into the ed_val field. 364 The macros are HIP_HI_ANY, HIP_HI_ANY_PUB and HIP_HI_ANY_ANON. They 365 denote an ED value associated with a wildcard HI of any, public, or 366 anonymous type. This is useful to a ``server'' application that is 367 willing to accept connections to all of the HIs of the host. The 368 macros correspond to the sockets API macros INADDR_ANY and 369 IN6ADDR_ANY_INIT, but they are applicable on the HIP layer. It 370 should be noted that only one process at a time can bind with the 371 HIP_HI_*ANY macro on a certain port to avoid ambiguous bindings. 373 The native HIP API has a new resolver function which is used for 374 querying both endpoint identifiers and locators. The resolver 375 introduces a new data structure, which is used both as the input and 376 output argument for the resolver. The new structure, endpointinfo, 377 is shown in Figure 5. 379 struct endpointinfo { 380 int ei_flags; /* flags, e.g. EI_FALLBACK */ 381 int ei_family; /* e.g. PF_HIP */ 382 int ei_socktype; /* e.g. SOCK_STREAM */ 383 int ei_protocol; /* usually just zero */ 384 size_t ei_endpoint_len; /* length of the endpoint */ 385 struct sockaddr *ei_endpoint; /* endpoint socket address */ 386 char *ei_canonname; /* canonical name of the host */ 387 struct endpointinfo *ei_next; /* next endpoint */ 388 }; 390 Figure 5 392 The members of the endpointinfo structure are similar to addrinfo 393 structure, but the member names have a different prefix. The socket 394 address structure used for sockets API calls has been renamed to 395 ei_endpoint to emphasize the difference with the getaddrinfo 396 resolver. The family, ei_family, is set to PF_HIP when the socket 397 address structure contains an ED that refers to a HI. 399 The flags in the endpointinfo structure control the behavior of the 400 resolver and describe the attributes of the endpoints and locators. 401 The EI_ANON flag forces the resolver to query only for local 402 anonymous identifiers. The default action is first to resolve the 403 public endpoints and then the anonymous endpoints. 405 Some applications may prefer configuring the locators manually and 406 can set the EI_NOLOCATORS to prohibit the resolver from resolving any 407 locators. If the application wants to configure locators manually, 408 the EI_NOLOCATORS flag forces the resolver to discard the resolving 409 of locators. The EI_FALLBACK flag suggests the resolver to return 410 locators if no HIs are found. The ei_endpoint members in the 411 resolver output are then filled with IPv4 or IPv6 addresses and the 412 application can resort to plain TCP/IP connections using the IP 413 addresses returned. The fallback flag must be explicitly enabled in 414 the flags, because the resolver returns only HIs by default. The 415 EI_HI_ANY, EI_HI_ANY_PUB and EI_HI_ANY_ANON flags cause the resolver 416 to output only a single socket address containing an ED that would be 417 received using the corresponding HIP_HI_*ANY macro. 419 Application specified endpoint identifiers are essentially private 420 keys. To support application specified identifiers in the API, we 421 need new data structures for storing the private keys. The private 422 keys need an uniform format so that they can be easily used in API 423 calls. The keys are stored in the endpoint structures shown in 424 figure Figure 6. 426 struct endpoint { 427 se_length_t length; 428 se_family_t family; 429 }; 430 struct endpoint_hip { 431 se_length_t length; 432 se_family_t family; /* EF_HI */ 433 se_hip_flags_t flags; 434 union { 435 struct hip_host_id host_id; 436 hit_t hit; 437 } id; 438 }; 440 Figure 6 442 The structure endpoint represents a generic endpoint and the 443 endpoint_hip is the HIP specific endpoint. The HIP endpoint is 444 public by default unless HIP_ENDPOINT_FLAG_ANON flag is set in the 445 structure to anonymize the endpoint. The id union contains the HI in 446 the host_id member in the format specified in the HIP draft 447 [I-D.ietf-hip-base]. The draft does not specify the format for the 448 private key, so private key material is just appended to the host_id 449 and the length is adjusted accordingly. The flag 450 HIP_ENDPOINT_FLAG_PRIVATE is also set. The hit member of the union 451 is used only when the HIP_ENDPOINT_FLAG_HIT flag is set. 453 An optional extension to the getaddrinfo interface is introduced too. 454 A new flag, AI_HIP_RVS, is used both in the input and output of the 455 resolver. By default, the getaddrinfo resolver does not return IP 456 addresses belonging to a HIP rendezvous server. The resolver returns 457 rendezvous server addresses only when the AI_HIP_RVS flag is set in 458 the resolver hints. This way, legacy applications can never receive 459 any addresses belonging to a rendezvous server. The flag is also set 460 in the getaddrinfo resolver output to denote that the resolved 461 address belongs to a HIP rendezvous server. 463 A.2 Functions 465 The new functions introduced to the sockets API are described in this 466 section. 468 A.2.1 Resolver Interface 470 The native HIP API does not introduce changes to the interface syntax 471 of the fundamental sockets API functions bind, connect, send, sendto, 472 sendmsg, recv, recvfrom, and recvmsg. The application usually calls 473 the functions with sockaddr_ed structures instead of sockaddr_in or 474 sockaddr_in6 structures. The source of the sockaddr_ed structures in 475 the native HIP API is the resolver function getendpointinfo which is 476 shown in Figure 7. 478 int getendpointinfo(const char *nodename, 479 const char *servname, 480 const struct endpointinfo *hints, 481 struct endpointinfo **res) 482 void free_endpointinfo(struct endpointinfo *res) 484 Figure 7 486 The getendpointinfo function takes the nodename, servname, and hints 487 as its input arguments. It places the result of the query into the 488 res argument. The return value is zero on success, or a non-zero 489 error value on error. The nodename argument specifies the host name 490 to be resolved; a NULL argument denotes the local host. The servname 491 parameter sets the port number to be set in the socket addresses in 492 the res output argument. Both the nodename and servname cannot be 493 NULL. 495 The output argument res is dynamically allocated by the resolver. 496 The application must free it with the free_endpointinfo function. It 497 contains a linked list of the resolved endpoints. The input argument 498 hints acts like a filter that defines the attributes required from 499 the resolved endpoints. For example, setting the flag 500 HIP_ENDPOINT_FLAG_ANON in the hints forces the resolver to return 501 only anonymous endpoints in the output argument res. If the hints 502 argument is zero, any kind of endpoints are acceptable. 504 A.2.2 Application Specified Identities 506 Application specified local and peer endpoints can be retrieved from 507 files using the function shown in Figure 8. The function 508 hip_endpoint_load_pem is used for retrieving a private or public key 509 from a given file filename. The file must be in PEM encoded format. 510 The result is allocated dynamically and stored into the endpoint 511 argument. The return value of the function is zero on success, or a 512 non-zero error value on failure. The result is deallocated with the 513 free system call. 515 int hip_endpoint_pem_load(const char *filename, 516 struct endpoint **endpoint) 518 Figure 8 520 The endpoint structure cannot be used directly in the sockets API 521 function calls. The application must convert the endpoint into an ED 522 first. Local endpoints are converted with the getlocaled function 523 and peer endpoints with getpeered function. The functions are 524 illustrated in Figure 9. Both of functions are used in a similar 525 way. 527 struct sockaddr_ed *getlocaled(const struct endpoint *endpoint, 528 const char *servname, 529 const struct addrinfo *addrs, 530 const struct if_nameindex *ifaces, 531 int flags) 532 struct sockaddr_ed *getpeered(const struct endpoint *endpoint, 533 const char *servname, 534 const struct addrinfo *addrs, 535 int flags) 537 Figure 9 539 The result of the conversion, an ED socket address, is returned by 540 the functions. A failure in the conversion causes a NULL return 541 value to be returned and the errno to be set accordingly. The caller 542 of the functions is responsible of freeing the returned socket 543 address structure. 545 The endpoint argument is retrieved e.g. with the 546 hip_endpoint_load_pem function. If the endpoint is NULL, an 547 arbitrary HI of the host is selected and associated with the ED value 548 of the third argument. 550 The servname argument is the service string. The function converts 551 it to a numeric port number and fills the port number into the 552 returned ED socket structure for the convenience of the application. 554 The addrs argument defines the initial IP addresses of the local host 555 or peer host. The argument is a pointer to a linked list of addrinfo 556 structures containing the initial addresses of the peer. The list 557 pointer can be obtained with a getaddrinfo [RFC3493] function call. 558 A NULL pointer indicates that the application trusts the host to 559 already know the locators of the peer. We recommend that a NULL 560 pointer is not given to the getpeered function to ensure reachability 561 with the peer. 563 The getlocaled function accepts also a list of network interface 564 indexes in the ifaces argument. The list can be obtained with the 565 if_nameindex [RFC3493] function call. A NULL list pointer indicates 566 all the interfaces of the local host. Both the IP addresses and 567 interfaces can be combined to select a specific address from a 568 specific interface. 570 The last argument is the flags. The following flags are valid only 571 for the getlocaled function: 572 o HIP_ED_*ANY correspond to the use of the HIP_HI_*ANY macros. 573 o Flags HIP_HI_REUSE_UID, HIP_HI_REUSE_GID and HIP_HI_REUSE_ANY 574 allow the HI binding to be reused for processes with the same UID, 575 GID or any UID as the calling process. 576 o Flags HIP_ED_IP and HIP_ED_IPV6 are used for limiting the address 577 family scope of the interfaces. 579 It should noticed that the HIP_HI_ANY, HIP_HI_ANY_PUB and 580 HIP_HI_ANY_ANON macros can be defined as calls to the getlocaled call 581 with a NULL endpoint, NULL interface, NULL address argument and the 582 flag corresponding to the macro name set. 584 A.2.3 Querying Endpoint Related Information 586 The getlocaled and getpeered functions have also their reverse 587 counterparts. Given an ED, the getlocaledinfo and getpeeredinfo 588 functions search for the HI and the current set of locators 589 associated with the ED. The first argument is the ED to be searched 590 for. The functions write the results of the search, the HIs and 591 locators, to the rest of the function arguments. The function 592 interfaces are depicted in figure Figure 10. The caller of the 593 functions is responsible for freeing the memory reserved for the 594 search results. 596 int getlocaledinfo(const struct sockaddr_ed *my_ed, 597 struct endpoint **endpoint, 598 struct addrinfo **addrs, 599 struct if_nameindex **ifaces) 600 int getpeeredinfo(const struct sockaddr_ed *peer_ed, 601 struct endpoint **endpoint, 602 struct addrinfo **addrs) 604 Figure 10 606 The getlocaledinfo and getpeeredinfo functions are especially useful 607 for an advanced application that receives multiple EDs from the 608 resolver. The advanced application can query the properties of the 609 EDs using getlocaledinfo and getpeeredinfo functions and select the 610 ED that matches the desired properties. 612 A.2.4 Socket Options 614 As usually, getting and setting of HIP socket options is done using 615 getsockopt and setsockopt functions. To set HIP layer specific 616 socket options, the first argument must be a socket descriptor that 617 was instantiated with PF_HIP as the domain, and the second argument 618 must be specified as IPPROTO_HIP 620 Some HIP socket option names are listed in Table 2. The length of 621 the option must be natural word size of the underlying processor, 622 typically 32 or 64 bits. The purpose of the option value must be 623 interpreted in context of the protocol specifications 624 [I-D.ietf-hip-base][I-D.ietf-hip-mm]. 626 The socket options must be set before the hosts have established HIP 627 SA. The implementation may refuse to set the socket options if there 628 is already an existing SA associated with the given socket. 630 +---------------------------------+---------------------------------+ 631 | Socket Options | Purpose | 632 +---------------------------------+---------------------------------+ 633 | SO_HIP_CHALLENGE_SIZE | Puzzle challenge size | 634 | | | 635 | SO_HIP_HIP_TRANSFORMS | Integer array of the preferred | 636 | | HIP transforms | 637 | | | 638 | SO_HIP_ESP_TRANSFORMS | Integer array of the preferred | 639 | | ESP transforms | 640 | | | 641 | SO_HIP_DH_GROUP_IDS | Integer array of the preferred | 642 | | Diffie-Hellman group IDs | 643 | | | 644 | SO_HIP_SA_LIFETIME | Socket association lifetime in | 645 | | seconds | 646 | | | 647 | SO_HIP_RETRANS_INIT_TIMEOUT | HIP initial retransmission | 648 | | timeout | 649 | | | 650 | SO_HIP_RETRANS_INTERVAL | HIP retransmission interval in | 651 | | seconds | 652 | | | 653 | SO_HIP_RETRANS_ATTEMPTS | Number of retransmission | 654 | | attempts | 655 | | | 656 | SO_HIP_AF_FAMILY | The preferred IP address | 657 | | family. The default family is | 658 | | AF_ANY. | 659 | | | 660 | SO_HIP_PIGGYPACK | If set to one, HIP | 661 | | piggy-packing is preferred. | 662 | | Zero if piggy-packing must not | 663 | | be used. | 664 | | | 665 | SO_HIP_OPPORTUNISTIC | Try HIP in opportunistic mode | 666 | | if only the locators of the | 667 | | peer are known. | 668 | | | 669 | SO_HIP_OPP_FALLBACK | The same as above, but fall | 670 | | back to plain TCP/IP if base | 671 | | exchange failed | 672 | | | 673 | SO_HIP_BEX_FALLBACK | Try normal base exchange, but | 674 | | fall back to plain TCP/IP if | 675 | | the base exchange fails. | 676 +---------------------------------+---------------------------------+ 678 Table 2 680 Intellectual Property Statement 682 The IETF takes no position regarding the validity or scope of any 683 Intellectual Property Rights or other rights that might be claimed to 684 pertain to the implementation or use of the technology described in 685 this document or the extent to which any license under such rights 686 might or might not be available; nor does it represent that it has 687 made any independent effort to identify any such rights. Information 688 on the procedures with respect to rights in RFC documents can be 689 found in BCP 78 and BCP 79. 691 Copies of IPR disclosures made to the IETF Secretariat and any 692 assurances of licenses to be made available, or the result of an 693 attempt made to obtain a general license or permission for the use of 694 such proprietary rights by implementers or users of this 695 specification can be obtained from the IETF on-line IPR repository at 696 http://www.ietf.org/ipr. 698 The IETF invites any interested party to bring to its attention any 699 copyrights, patents or patent applications, or other proprietary 700 rights that may cover technology that may be required to implement 701 this standard. Please address the information to the IETF at 702 ietf-ipr@ietf.org. 704 Disclaimer of Validity 706 This document and the information contained herein are provided on an 707 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 708 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 709 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 710 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 711 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 712 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 714 Copyright Statement 716 Copyright (C) The Internet Society (2005). This document is subject 717 to the rights, licenses and restrictions contained in BCP 78, and 718 except as set forth therein, the authors retain all their rights. 720 Acknowledgment 722 Funding for the RFC Editor function is currently provided by the 723 Internet Society.