idnits 2.17.1 draft-ietf-hip-native-api-01.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 on line 18. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 749. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 760. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 767. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 773. 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 document has an RFC 3978 Section 5.2(a) Derivative Works Limitation clause. == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 372 has weird spacing: '... int ai_...' == Line 373 has weird spacing: '... int ai_...' == Line 374 has weird spacing: '... int ai_...' == Line 375 has weird spacing: '... int ai_...' -- 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 (March 7, 2007) is 6258 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) -- Possible downref: Normative reference to a draft: ref. 'I-D.henderson-hip-applications' == Outdated reference: A later version (-10) exists of draft-ietf-hip-base-07 ** Downref: Normative reference to an Experimental draft: draft-ietf-hip-base (ref. 'I-D.ietf-hip-base') == Outdated reference: A later version (-17) exists of draft-ietf-shim6-multihome-shim-api-01 ** Downref: Normative reference to an Informational draft: draft-ietf-shim6-multihome-shim-api (ref. 'I-D.ietf-shim6-multihome-shim-api') == Outdated reference: A later version (-01) exists of draft-komu-btns-api-00 -- Possible downref: Non-RFC (?) normative reference: ref. 'POSIX' ** Downref: Normative reference to an Informational RFC: RFC 3493 Summary: 4 errors (**), 0 flaws (~~), 9 warnings (==), 10 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: Standards Track Technology 5 Expires: September 8, 2007 March 7, 2007 7 Native Application Programming Interfaces for SHIM Layer Prococols 8 draft-ietf-hip-native-api-01 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 This document may not be modified, and derivative works of it may not 17 be created, except to publish it as an RFC and to translate it into 18 languages other 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 September 8, 2007. 38 Copyright Notice 40 Copyright (C) The IETF Trust (2007). 42 Abstract 44 This document proposes extensions to the current networking APIs for 45 protocols based on identifier/locator split. Currently, the document 46 focuses on HIP, but the extensions can be used also by other 47 protocols implementing identifier locator split. Using the API 48 extensions, new SHIM aware applications can gain a better control of 49 the SHIM layer and endpoint identifiers. For example, the 50 applications can query and set SHIM related attributes, or specify 51 their own endpoint identifiers for a host. In addition, a new 52 indirection element called endpoint descriptor is defined for SHIM 53 aware applications that can be used for implementing opportunistic 54 mode in a clean way. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Design Architecture . . . . . . . . . . . . . . . . . . . . . 4 61 2.1. Endpoint Descriptor . . . . . . . . . . . . . . . . . . . 4 62 2.2. Layering Model . . . . . . . . . . . . . . . . . . . . . . 4 63 2.3. Namespace Model . . . . . . . . . . . . . . . . . . . . . 5 64 2.4. Socket Bindings . . . . . . . . . . . . . . . . . . . . . 6 66 3. Interface Syntax and Description . . . . . . . . . . . . . . . 7 67 3.1. Data Structures . . . . . . . . . . . . . . . . . . . . . 8 68 3.2. Functions . . . . . . . . . . . . . . . . . . . . . . . . 10 69 3.2.1. Resolver Interface . . . . . . . . . . . . . . . . . . 11 70 3.2.2. Application Specified Identities . . . . . . . . . . . 11 71 3.2.3. Querying Endpoint Related Information . . . . . . . . 13 72 3.2.4. HIP Related Policy Attributes . . . . . . . . . . . . 14 74 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 76 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 78 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 81 7.1. Normative References . . . . . . . . . . . . . . . . . . . 15 82 7.2. Informative References . . . . . . . . . . . . . . . . . . 16 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 85 Intellectual Property and Copyright Statements . . . . . . . . . . 18 87 1. Introduction 89 The extensions defined in this draft can be used also by other 90 protocols based on the identifier/locator split. However, this 91 documented focuses mainly to HIP. 93 Host Identity Protocol proposes a new cryptographic namespace and a 94 new layer to the TCP/IP architecture. Applications can see these new 95 changes in the networking stacks with varying degrees of visibility. 96 [I-D.henderson-hip-applications] discusses the lowest levels of 97 visibility in which applications are either completely or partially 98 unaware of HIP. In this document, we discuss about the highest level 99 of visibility. The applications are completely HIP aware and can 100 control the HIP layer and Host Identifiers. The applications aquery 101 and set security related attributes and even create their own Host 102 Identifiers. 104 Existing applications can be used with HIP as described in 105 [I-D.henderson-hip-applications]. The reason why HIP can be used in 106 a backwards compatible way lies in the identifiers. A HIP enabled 107 system can support the use of LSIs, HITs and even IP addresses as 108 upper layer identifiers to accomodate varying application 109 requirements. However, these types of identifiers are not forwards 110 compatible. The length of HIT may turn out insecure in the future. 111 There may be a need to change the HITs on the fly to an already 112 connected socket for dynamic session mobility. Or, the socket is 113 going to be associated to multiple HITs for HIP based multicast. 115 To support forwards compatibility, we introduce a new, generalized 116 identifier called the endpoint descriptor (ED). The ED acts as a 117 handle to the actual identifier that separates application layer 118 indentifiers from the lower layer identifiers. 120 The ED can already now be used for implementing HIP opportunistic 121 mode in a clean way. The problem with implementing HIP opportunistic 122 mode is that e.g. sockets API connect() call should be bound to a HIT 123 in order to use HIP, but the HIT is unknown until the reception the 124 R1 packet. At this point it is too late to change the binding e.g. 125 from a IP to HIT. However, the ED has to property of late binding 126 and therefore provides a cleaner way to implement the opportunistic 127 mode. 129 The ED socket address structure does not reveal the transport 130 layerport number to the application even though it is possible to 131 request it explicitly. This makes it possible to change the port 132 number dynamically without affecting the application. Also, it seems 133 that the port number is irrelevant, or even misleading, in todays 134 NATted networks to the application. 136 The document also introduces a new address family, PF_SHIM, for 137 sockets that use EDs. The new family is a direct consequence of 138 introducing a new address type (ED) to the sockets API. It can also 139 be used for quick detection of SHIM support in the localhost. This 140 is especially useful discover when SHIM aware applications are tried 141 on a host that does not support SHIM. 143 The ED concept is similar to Local Scope Identifier 144 [I-D.henderson-hip-applications] in the sense that it is also valid 145 only within a host. However, it has some differences. A minor 146 difference is that two LSIs are the same when they refer to the same 147 endpoint, but ED does not have this constraint. LSIs have a prefix 148 to separate them from IP addresses, but ED do not. However, the main 149 reason why ED is not denoted as LSI in this document is that the LSIs 150 are bound to AF_INET sockets whereas EDs are bound to PF_SHIM 151 sockets. 153 2. Design Architecture 155 In this section, the native SHIM API design is described from an 156 architectural point of view. We introduce the ED concept, which is a 157 central idea in the API. We describe the layering and namespace 158 models along with the socket bindings. We conclude the discussion 159 with a description of the endpoint identifier resolution mechanism. 161 2.1. Endpoint Descriptor 163 The representation of endpoints is hidden from the applications. The 164 ED is a ``handle'' to a HI. A given ED serves as a pointer to the 165 corresponding HI entry in the HI database of the host. It should be 166 noticed that the ED cannot be used as a referral that is passed from 167 one host to another because it has only local significance. 169 2.2. Layering Model 171 The application layer accesses the transport layer via the socket 172 interface. The application layer uses the traditional TCP/IP IPv4 or 173 IPv6 interface, or the new native SHIM API interface provided by the 174 socket layer. The layering model is illustrated in Figure 1. For 175 simplicity, the IPsec layer has been excluded from the figure. 177 +--------------------------------+ 178 Application Layer | Application | 179 +----------+----------+----------+ 180 Socket Layer | IPv4 API | IPv6 API | SHIM API | 181 +----------+----+-----+----------+ 182 Transport Layer | TCP | UDP | 183 +---------------+----------------+ 184 SHIM Layer | HIP and other SHIMs | 185 +---------------+----------------+ 186 Network Layer | IPv4 | IPv6 | 187 +---------------+----------------+ 188 Link Layer | Ethernet | Etc | 189 +---------------+----------------+ 191 Figure 1 193 The SHIM layer is as a shim/wedge layer between the transport and 194 network layers. The datagrams delivered between the transport and 195 network layers are intercepted in the SHIM layer to see if the 196 datagrams are SHIM related and require SHIM intervention. 198 2.3. Namespace Model 200 The namespace model is shown in from HIP view point. The namespace 201 identifiers are described in this section. 203 +-------------------+-----------------------+ 204 | Layer | Identifier | 205 +-------------------+-----------------------+ 206 | User Interface | FQDN | 207 | Application Layer | ED, port and protocol | 208 | Transport Layer | HI, port | 209 | SHIM Layer | HI | 210 | Network Layer | IP address | 211 +-------------------+-----------------------+ 213 Table 1 215 People prefer human-readable names when referring to network 216 entities. The most commonly used identifier in the User Interface is 217 the FQDN, but there are also other ways to name network entities. 218 The FQDN format is still the preferred UI level identifier in the 219 context of the native SHIM API. 221 In the current API, connection associations in the application layer 222 are uniquely distinguished by the source IP address, destination IP 223 address, source port, destination port, and protocol. HIP changes 224 this model by using HIT in the place of IP addresses. The HIP model 225 is further expanded in the native HIP API model by using ED instead 226 of HITs. Now, the application layer uses source ED, destination ED, 227 source port, destination port, and transport protocol type, to 228 distinguish between the different connection associations. 230 Basically, the difference between the application and transport layer 231 identifiers is that the transport layer uses HIs instead of EDs. The 232 TLI is named with source HI, destination HI, source port, and 233 destination port at the transport layer. 235 Correspondingly, the HIP layer uses HIs as identifiers. The HIP 236 security associations are based on source HI and destination HI 237 pairs. 239 The network layer uses IP addresses, i.e., locators, for routing 240 purposes. The network layer interacts with the HIP layer to exchange 241 information about changes in the local interfaces addresses and peer 242 addresses. 244 2.4. Socket Bindings 246 A HIP based SHIM socket is associated with one source and one 247 destination ED, along with their port numbers and protocol type. The 248 relationship between a socket and ED is a many-to-one one. Multiple 249 EDs can be associated with a single HI. Further, the source HI is 250 associated with a set of network interfaces at the local host. The 251 destination HI, in turn, is associated with a set of destination 252 addresses of the peer. The socket bindings are visualized in 253 Figure 2. 255 1 +---------+ * * +--------+ * * +-----------+ 256 +---+ Src EID +------+ Src HI +------+ Src Iface | 257 +--------+ * | +---------+ +--------+ +-----------+ 258 | HIP +------+ 259 | | 260 | Socket +------+ 261 +--------+ * | +---------+ +--------+ +-----------+ 262 +---+ Dst EID +------+ Dst HI +------+ Dst IP | 263 1 +---------+ * * +--------+ * * +-----------+ 265 Figure 2 267 The relationship between a source ED and a source HI is usually many- 268 to-one one, but it can be also many-to-many on certain cases. There 269 are two refinements to the relationship. First, a listening socket 270 is allowed to accept connections from all local HIs of the host. 271 Second, the opportunistic mode allows the base exchange to be 272 initiated to an unknown destination HI. In a way, the relationship 273 between the local ED and local HI is a many-to-undefined relationship 274 momentarily in both of the cases, but once the connection is 275 established, the ED will be permanently associated with a certain HI. 277 The DNS based endpoint discovery mechanism is illustrated in 278 Figure 3. The application calls the resolver (step a.) to resolve an 279 FQDN (step b.). The DNS server responds with a ED and a set of 280 locators (step c.). The resolver does not directly pass the ED and 281 the locators to the application, but sends them to the SHIM module 282 (step d.). Finally, the resolver receives an ED from the SHIM module 283 (step e.) and passes the ED to the application (step f.). 285 +----------+ 286 | | 287 | DNS | 288 | | 289 +----------+ 290 ^ | 291 b. | | c. 292 | v 293 +-------------+ a. +----------+ 294 | |----------->| | 295 | Application | | Resolver | 296 | |<-----------| | 297 +-------------+ f. +----------+ 298 ^ | 299 e. | | d. 300 | v 301 +----------+ 302 | | 303 | SHIM | 304 | | 305 +----------+ 307 Figure 3 309 The application can also receive multiple EDs from the resolver when 310 the FQDN is associated with multiple EIDs. The endpoint discovery 311 mechanism is still almost the same. The difference is that the DNS 312 returns a set of EIDs (along with the associated locators) to the 313 resolver. The resolver sends all of them to the SHIM module and 314 receives a set of EDs in return, each ED corresponding to a single 315 HI. Finally, the EDs are sent to the application. 317 3. Interface Syntax and Description 319 In this section, we describe the native SHIM API using the syntax of 320 the C programming language and present only the ``external'' 321 interfaces and data structures that are visible to the applications. 322 We limit the description to those interfaces and data structures that 323 are either modified or completely new, because the native SHIM API is 324 otherwise identical to the sockets API [POSIX]. 326 3.1. Data Structures 328 We introduce a new protocol family, PF_SHIM, for the sockets API. 329 The AF_SHIM constant is an alias for it. The use of the PF_SHIM 330 constant is mandatory with the socket function if the native SHIM API 331 is to be used in the application. The PF_SHIM constant is given as 332 the first argument (domain) to the socket function. 334 The ED abstraction is realized in the sockaddr_ed structure, which is 335 shown in Figure 4. The family of the socket, ed_family, is set to 336 PF_SHIM. The port number ed_port is two octets and the ED value 337 ed_val is four octets. The ED value is just an opaque number to the 338 application. The application should not try to associate it directly 339 to a EID or even compare it to other ED values, because there are 340 separate functions for those purposes. The ED family is stored in 341 host byte order. The ED value is stored in network byte order. It 342 should be noticed that the port number is not present in the socket 343 address structure, but it can be queried with the functions in 344 section Section 3.2.2. 346 struct sockaddr_ed { 347 unsigned short int ed_family; 348 sa_ed_t ed_val; 349 } 351 Figure 4 353 The ed_val field is usually set by special native SHIM API functions, 354 which are described in the following section. However, three special 355 macros can be used to directly set a value into the ed_val field. 356 The macros are SHIM_ED_ANY, SHIM_ED_ANY_PUB and SHIM_ED_ANY_ANON. 357 They denote an ED value associated with a wildcard HI of any, public, 358 or anonymous type. They are useful to a ``server'' application that 359 is willing to accept connections to all of the HIs of the host. The 360 macros correspond to the sockets API macros INADDR_ANY and 361 IN6ADDR_ANY_INIT, but they are applicable on the SHIM layer. It 362 should be noted that only one process at a time can bind with the 363 SHIM_ED_*ANY macro on a certain port to avoid ambiguous bindings. 365 The native SHIM API has a new resolver function which is used for 366 querying both endpoint identifiers and locators. The resolver 367 introduces a new data structure, which is used both as the input and 368 output argument for the resolver. We reuse the existing resolver 369 datastructure shown in Figure 5. 371 struct addrinfo { 372 int ai_flags; /* e.g. AI_ED */ 373 int ai_family; /* e.g. PF_SHIM */ 374 int ai_socktype; /* e.g. SOCK_STREAM */ 375 int ai_protocol; /* usually just zero */ 376 size_t ai_addrlen; /* length of the endpoint */ 377 struct sockaddr *ai_addr; /* endpoint socket address */ 378 char *ai_canonname; /* canon. name of the host */ 379 struct addrinfo *ai_next; /* next endpoint */ 380 }; 382 Figure 5 384 In addrinfo structures, the family field is set to PF_SHIM when the 385 socket address structure contains an ED that refers to a SHIM 386 identifier, such as HI. 388 The flags in the addrinfo structure control the behavior of the 389 resolver and describe the attributes of the endpoints and locators: 391 o The flag AI_ED must be set, or otherwise the resolver does not 392 return EDs to guarantee that legacy applications won't break. 393 When AI_ED is set, the resolver returns a linked list which 394 contains first the sockaddr_ed structures for SHIM identifiers if 395 any was found. After that, any other type of socket addresses are 396 returned except that HITs in sockaddr_in6 format are excluded 397 because they were already included in the returned sockaddr_ed 398 structures. 400 o When querying local identifiers, the AI_ED_ANON flag forces the 401 resolver to query only local anonymous identifiers. The default 402 action is first to resolve the public endpoints and then the 403 anonymous endpoints. 405 o Some applications may prefer configuring the locators manually and 406 can set the AI_ED_NOLOCATORS flag to prohibit the resolver from 407 resolving any locators. 409 o The AI_ED_ANY, AI_ED_ANY_PUB and AI_ED_ANY_ANON flags cause the 410 resolver to output only a single socket address containing an ED 411 that would be received using the corresponding SHIM_ED_*ANY macro. 412 When these flags are used for resolving local addresses, they 413 allow wildcard late binding to certain types of local idenfiers. 414 When the flags are used for peer resolving, they allow to contact 415 the peer using opportunistic mode. 417 o The getaddrinfo resolver does not return IP addresses belonging to 418 a SHIM rendezvous server unless AI_ED is defined. AI_ED_RVS, can 419 appear both in the input and output arguments of the resolver. In 420 the input, it can be used for resolving only rendezvous server 421 addresses. On the output, it denotes that the address is a 422 rendezvous rather than end-point address. 424 Application specified endpoint identifiers are essentially private 425 keys. To support application specified identifiers in the API, we 426 introduce new data structures for storing the private keys. The 427 private keys need an uniform format so that they can be easily used 428 in the API calls. The keys are stored in the endpoint structures as 429 shown in Figure 6. 431 struct endpoint { 432 se_length_t length; 433 se_family_t family; 434 }; 435 struct endpoint_hip { 436 se_length_t length; 437 se_family_t family; /* EF_HI in the case of HIP */ 438 se_hip_flags_t flags; 439 union { 440 struct hip_host_id host_id; 441 hit_t hit; 442 } id; 443 }; 445 Figure 6 447 The endpoint structure represents a generic endpoint and the 448 endpoint_hip structure represents a HIP specific endpoint. The 449 family field distinguishes whether the identifier is HIP or other 450 protocol related. The HIP endpoint is public by default unless 451 SHIM_ENDPOINT_FLAG_ANON flag is set in the structure to anonymize the 452 endpoint. The id union contains the HI in the host_id member in the 453 format specified in [I-D.ietf-hip-base]. If the key is private, the 454 material is appended to the host_id with the length adjusted 455 accordingly. The flag SHIM_ENDPOINT_FLAG_PRIVATE is also set. The 456 hit member of the union is used only when the SHIM_ENDPOINT_FLAG_HIT 457 flag is set. 459 3.2. Functions 461 In this section, some existing sockets API functions are reintroduced 462 along with their additions. Also, some new auxiliary functions are 463 defined. 465 3.2.1. Resolver Interface 467 The native SHIM API does not introduce changes to the interface 468 syntax of the primitive sockets API functions bind, connect, send, 469 sendto, sendmsg, recv, recvfrom, and recvmsg. However, the 470 application usually calls the functions with sockaddr_ed structures 471 instead of sockaddr_in or sockaddr_in6 structures. The source of the 472 sockaddr_ed structures in the native SHIM API is the resolver 473 function getaddrinfo [RFC3493] which is shown in Figure 7. 475 int getaddrinfo(const char *nodename, 476 const char *servname, 477 const struct addrinfo *hints, 478 struct addrinfo **res) 479 void free_addrinfo(struct addrinfo *res) 481 Figure 7 483 The getaddrinfo function takes the nodename, servname, and hints as 484 its input arguments. It places the result of the query into the res 485 argument. The return value is zero on success, or a non-zero error 486 value on error. The nodename argument specifies the host name to be 487 resolved; a NULL argument denotes the local host. The servname 488 parameter sets the port number to be set in the socket addresses in 489 the res output argument. Both the nodename and servname cannot be 490 NULL. 492 The output argument res is dynamically allocated by the resolver. 493 The application must free res argument with the free_addrinfo 494 function. The res argument contains a linked list of the resolved 495 endpoints. The input argument hints acts like a filter that defines 496 the attributes required from the resolved endpoints. For example, 497 setting the flag SHIM_ENDPOINT_FLAG_ANON in the hints forces the 498 resolver to return only anonymous endpoints in the output argument 499 res. A NULL hints argument indicates that any kind of endpoints are 500 acceptable. 502 3.2.2. Application Specified Identities 504 Application specified local and peer endpoints can be retrieved from 505 files using the function shown in Figure 8. The function 506 shim_endpoint_load_pem is used for retrieving a private or public key 507 from a given file filename. The file must be in PEM encoded format. 508 The result is allocated dynamically and stored into the endpoint 509 argument. The return value of the function is zero on success, or a 510 non-zero error value on failure. The result is deallocated with the 511 free system call. 513 int shim_endpoint_pem_load(const char *filename, 514 struct endpoint **endpoint) 516 Figure 8 518 Alternatively, the application can load the image directly from 519 memory as shown in Figure 9 521 int shim_endpoint_pem_load_str(const char *pem_str, 522 struct endpoint **endpoint); 524 Figure 9 526 The endpoint structure cannot be used directly in the sockets API 527 function calls. The application must convert the endpoint into an ED 528 first. Local endpoints are converted with the getlocaled function 529 and peer endpoints with getpeered function. The functions are 530 illustrated in Figure 10. 532 struct sockaddr_ed *getlocaled(const struct endpoint *endpoint, 533 const char *servname, 534 const struct addrinfo *addrs, 535 const struct if_nameindex *ifaces, 536 int flags) 537 struct sockaddr_ed *getpeered(const struct endpoint *endpoint, 538 const char *servname, 539 const struct addrinfo *addrs, 540 int flags) 542 Figure 10 544 The result of the conversion, an ED socket address, is returned by 545 both of the functions. A failure in the conversion causes a NULL 546 return value to be returned and the errno to be set accordingly. The 547 caller of the functions is responsible of freeing the returned socket 548 address structure. 550 The application can retrieve the endpoint argument e.g. with the 551 shim_endpoint_load_pem function. If the endpoint is NULL, the system 552 selects an arbitrary EID and associates it with the ED value of the 553 return value. 555 The servname argument is the service string. The function converts 556 it to a numeric port number and fills the port number into the 557 returned ED socket structure for the convenience of the application. 559 The addrs argument defines the initial IP addresses of the local host 560 or peer host. The argument is a pointer to a linked list of addrinfo 561 structures containing the initial addresses of the peer. The list 562 pointer can be obtained with a getaddrinfo [RFC3493] function call. 563 A NULL pointer indicates that the application trusts the host to 564 already know the locators of the peer. We recommend that a NULL 565 pointer is not given to the getpeered function to ensure reachability 566 with the peer. 568 The getlocaled function accepts also a list of network interface 569 indexes in the ifaces argument. The list can be obtained with the 570 if_nameindex [RFC3493] function call. A NULL list pointer indicates 571 all the interfaces of the local host. Both the IP addresses and 572 interfaces can be combined to select a specific address from a 573 specific interface. 575 The last argument is the flags. The following flags are valid only 576 for the getlocaled function: 578 o Flags SHIM_ED_REUSE_UID, SHIM_ED_REUSE_GID and SHIM_ED_REUSE_ANY 579 allow the EID (e.g. a large private key) to be reused for 580 processes with the same UID, GID or any UID as the calling 581 process. 583 o Flags SHIM_ED_IPV4 and SHIM_ED_IPV6 can be used for limiting the 584 address family scope of the local interface. 586 It should noticed that the SHIM_ED_ANY, SHIM_ED_ANY_PUB and 587 SHIM_ED_ANY_ANON macros can be implemented as calls to the getlocaled 588 call with a NULL endpoint, NULL interface, NULL address argument and 589 the flag corresponding to the macro name set. 591 3.2.3. Querying Endpoint Related Information 593 The getlocaled and getpeered functions have also their reverse 594 counterparts. Given an ED, the getlocaledinfo and getpeeredinfo 595 functions search for the EID (e.g. a HI) and the current set of 596 locators associated with the ED. The first argument is the ED to be 597 searched for. The functions write the results of the search, the 598 transport layer port number of the occupied by the correponding HIT, 599 the HIs and locators, to the rest of the function arguments. The 600 function interfaces are depicted in Figure 11. The caller of the 601 functions is responsible for freeing the memory reserved for the 602 search results. 604 int getlocaledinfo(const struct sockaddr_ed *my_ed, 605 struct in_port_t **port 606 struct endpoint **endpoint, 607 struct addrinfo **addrs, 608 struct if_nameindex **ifaces) 609 int getpeeredinfo(const struct sockaddr_ed *peer_ed, 610 struct in_port_t **port 611 struct endpoint **endpoint, 612 struct addrinfo **addrs) 614 Figure 11 616 The getlocaledinfo and getpeeredinfo functions are especially useful 617 for an advanced application that receives multiple EDs from the 618 resolver. The advanced application can query the properties of the 619 EDs using getlocaledinfo and getpeeredinfo functions and select the 620 ED that matches the desired properties. 622 3.2.4. HIP Related Policy Attributes 624 Multihoming related attributes are defined in 625 [I-D.ietf-shim6-multihome-shim-api]. It also specifies an event 626 driven API for application, which can be used for listening for 627 changes in locators. 629 HIP related policy attributes are accessed using the definitions in 630 [I-D.komu-btns-api] 632 Some of the policy attributes must be set before the hosts have 633 established connection. The implementation may refuse to accept the 634 option when there is already an existing connection and dynamic 635 renegotiation of the option is not possible. In addition, the SHIM 636 may return an error value if the corresponding SHIM protocol does not 637 support the given option. 639 Table 2shows HIP related policy attributes that are accessed with the 640 APIs defined in [I-D.komu-btns-api]. 642 +---------------------+---------------------------------------------+ 643 | Attribute | Purpose | 644 +---------------------+---------------------------------------------+ 645 | IPSEC_ESP_TRANSFORM | Preferred ESP transform | 646 | IPSEC_SA_LIFETIME | Preferred IPsec SA lifetime in seconds | 647 | SHIM_PROTOCOL | Get or set current SHIM protocol. Currently | 648 | | only PF_HIP is defined. | 649 | SHIM_CHALLENGE_SIZE | Puzzle challenge size | 650 | SHIM_SHIM_TRANSFORM | Preferred SHIM transform | 651 | SHIM_DH_GROUP_IDS | The preferred Diffie-Hellman Group | 652 | SHIM_AF_FAMILY | The preferred locator family. The default | 653 | | family is AF_ANY. | 654 | SHIM_FAST_FALLBACK | If set to one, use the extensions in | 655 | | [I-D.lindqvist-hip-opportunistic] | 656 | SHIM_FAST_HANDSHAKE | If set to one, use the extensions in | 657 | | [I-D.lindqvist-hip-tcp-piggybacking] | 658 +---------------------+---------------------------------------------+ 660 Table 2 662 4. IANA Considerations 664 No IANA considerations. 666 5. Security Considerations 668 To be done. 670 6. Acknowledgements 672 Jukka Ylitalo and Pekka Nikander have contributed many ideas, time 673 and effort to the native HIP API. Thomas Henderson, Kristian Slavov, 674 Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew 675 McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, 676 Anthony Joseph, Teemu Koponen and Juha-Matti Tapio have also provided 677 valuable ideas and feedback. 679 7. References 681 7.1. Normative References 683 [I-D.henderson-hip-applications] 684 Henderson, T. and P. Nikander, "Using HIP with Legacy 685 Applications", draft-henderson-hip-applications-03 (work 686 in progress), May 2006. 688 [I-D.ietf-hip-base] 689 Moskowitz, R., "Host Identity Protocol", 690 draft-ietf-hip-base-07 (work in progress), February 2007. 692 [I-D.ietf-shim6-multihome-shim-api] 693 Komu, M., "Socket Application Program Interface (API) for 694 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-01 695 (work in progress), October 2006. 697 [I-D.komu-btns-api] 698 Komu, M., "IPsec Application Programming Interfaces", 699 draft-komu-btns-api-00 (work in progress), October 2006. 701 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 702 Std. 1003.1-2001 Standard for Information Technology - 703 Portable Operating System Interface (POSIX)", Dec 2001. 705 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 706 Stevens, "Basic Socket Interface Extensions for IPv6", 707 RFC 3493, February 2003. 709 7.2. Informative References 711 [I-D.lindqvist-hip-opportunistic] 712 Lindqvist, J., "Establishing Host Identity Protocol 713 Opportunistic Mode with TCP Option", 714 draft-lindqvist-hip-opportunistic-01 (work in progress), 715 March 2006. 717 [I-D.lindqvist-hip-tcp-piggybacking] 718 Lindqvist, J., "Piggybacking TCP to Host Identity 719 Protocol", draft-lindqvist-hip-tcp-piggybacking-00 (work 720 in progress), July 2006. 722 Author's Address 724 Miika Komu 725 Helsinki Institute for Information Technology 726 Tammasaarenkatu 3 727 Helsinki 728 Finland 730 Phone: +358503841531 731 Fax: +35896949768 732 Email: miika@iki.fi 733 URI: http://www.iki.fi/miika/ 735 Full Copyright Statement 737 Copyright (C) The IETF Trust (2007). 739 This document is subject to the rights, licenses and restrictions 740 contained in BCP 78, and except as set forth therein, the authors 741 retain all their rights. 743 This document and the information contained herein are provided on an 744 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 745 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 746 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 747 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 748 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 749 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 751 Intellectual Property 753 The IETF takes no position regarding the validity or scope of any 754 Intellectual Property Rights or other rights that might be claimed to 755 pertain to the implementation or use of the technology described in 756 this document or the extent to which any license under such rights 757 might or might not be available; nor does it represent that it has 758 made any independent effort to identify any such rights. Information 759 on the procedures with respect to rights in RFC documents can be 760 found in BCP 78 and BCP 79. 762 Copies of IPR disclosures made to the IETF Secretariat and any 763 assurances of licenses to be made available, or the result of an 764 attempt made to obtain a general license or permission for the use of 765 such proprietary rights by implementers or users of this 766 specification can be obtained from the IETF on-line IPR repository at 767 http://www.ietf.org/ipr. 769 The IETF invites any interested party to bring to its attention any 770 copyrights, patents or patent applications, or other proprietary 771 rights that may cover technology that may be required to implement 772 this standard. Please address the information to the IETF at 773 ietf-ipr@ietf.org. 775 Acknowledgment 777 Funding for the RFC Editor function is provided by the IETF 778 Administrative Support Activity (IASA).