idnits 2.17.00 (12 Aug 2021) /tmp/idnits23758/draft-komu-shim-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 on line 18. -- Found old boilerplate from RFC 3978, Section 5.5 on line 685. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 696. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 703. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 709. ** 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. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard 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 RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 310 has weird spacing: '... int ai_...' == Line 311 has weird spacing: '... int ai_...' == Line 312 has weird spacing: '... int ai_...' == Line 313 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 (June 21, 2006) is 5812 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: Non-RFC (?) normative reference: ref. '1' ** Downref: Normative reference to an Informational RFC: RFC 3493 (ref. '2') == Outdated reference: draft-ietf-hip-base has been published as RFC 5201 ** Downref: Normative reference to an Experimental draft: draft-ietf-hip-base (ref. '3') == Outdated reference: draft-ietf-hip-mm has been published as RFC 5206 ** Downref: Normative reference to an Experimental draft: draft-ietf-hip-mm (ref. '4') -- Possible downref: Normative reference to a draft: ref. '5' Summary: 7 errors (**), 0 flaws (~~), 8 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 Expires: December 23, 2006 Technology 5 June 21, 2006 7 Native Application Programming Interfaces for SHIM Layer Prococols 8 draft-komu-shim-native-api-00.txt 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 December 23, 2006. 38 Copyright Notice 40 Copyright (C) The Internet Society (2006). 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 similar "shim" layer protocols. Using the API extensions, 48 new SHIM aware applications can gain a better control of the SHIM 49 layer and endpoint identifiers. For example, the applications can 50 query and set SHIM related attributes, or specify their own endpoint 51 identifiers for a host. In addition, a new indirection element 52 called endpoint descriptor is defined for SHIM aware applications. 54 1. Introduction 56 The extensions defined in this draft can be used also by other 57 protocols based on the identifier/locator split. For example, SHIM6 58 and BTNS are possible such candidates. Related WG API drafts are 59 draft-sugimoto-multihome-shim-api and [6]. However, this draft 60 currently focuses on HIP. 62 Host Identity Protocol proposes a new cryptographic namespace and a 63 new layer to the TCP/IP architecture. Applications can see these new 64 changes in the networking stacks with varying degrees of visibility. 65 [5] discusses the lowest levels of visibility in which applications 66 are either completely or partially unaware of HIP. In this document, 67 we discuss about the highest level of visibility. The applications 68 are completely HIP aware and are given more control over the HIP 69 layer and identifiers. The applications are allowed to query and 70 configure security related attributes and even specify their own Host 71 Identifiers. 73 Legacy HIP applications can already use a variety of identifiers, 74 like LSIs, HITs and IP addresses as described in [5]. The varying 75 number of identifiers can be all be used for HIP based networking in 76 a easily deployable way. The proposed extensions could be as well 77 based on one of the existing formats, like HITs or public keys, but 78 they have their own problems. For example, the HIT format may change 79 in the future, and long, variable length public keys are not directly 80 applicable the current sockets API. In addition, there may be a need 81 for another new layer in the future, such as session layer, and 82 choosing any of the existing identifier formats may introduce 83 additional deployment problems for a new layer. We therefore propose 84 a new, generalized identifier called the endpoint descriptor (ED). 85 The ED acts as a handle to the actual identifier that separates 86 application layer indentifiers from the lower layer identifiers. 88 2. Design Architecture 90 In this section, the native SHIM API design is described from an 91 architectural point of view. We introduce the ED concept, which is a 92 central idea in the API. We describe the layering and namespace 93 models along with the socket bindings. We conclude the discussion 94 with a description of the endpoint identifier resolution mechanism. 96 2.1. Endpoint Descriptor 98 The representation of endpoints is hidden from the applications. The 99 ED is a ``handle'' to a HI. A given ED serves as a pointer to the 100 corresponding HI entry in the HI database of the host. It should be 101 noticed that the ED cannot be used as a referral that is passed from 102 one host to another because it has only local significance. 104 2.2. Layering Model 106 The application layer accesses the transport layer via the socket 107 interface. The application layer uses the traditional TCP/IP IPv4 or 108 IPv6 interface, or the new native SHIM API interface provided by the 109 socket layer. The layering model is illustrated in Figure 1. For 110 simplicity, the IPsec layer has been excluded from the figure. 112 +--------------------------------+ 113 Application Layer | Application | 114 +----------+----------+----------+ 115 Socket Layer | IPv4 API | IPv6 API | SHIM API | 116 +----------+----+-----+----------+ 117 Transport Layer | TCP | UDP | 118 +---------------+----------------+ 119 SHIM Layer | HIP and other SHIMs | 120 +---------------+----------------+ 121 Network Layer | IPv4 | IPv6 | 122 +---------------+----------------+ 123 Link Layer | Ethernet | Etc | 124 +---------------+----------------+ 126 Figure 1 128 The SHIM layer is as a shim/wedge layer between the transport and 129 network layers. The datagrams delivered between the transport and 130 network layers are intercepted in the SHIM layer to see if the 131 datagrams are SHIM related and require SHIM intervention. 133 2.3. Namespace Model 135 The namespace model is shown in from HIP view point. The namespace 136 identifiers are described in this section. 138 +-------------------+-----------------------+ 139 | Layer | Identifier | 140 +-------------------+-----------------------+ 141 | User Interface | FQDN | 142 | | | 143 | Application Layer | ED, port and protocol | 144 | | | 145 | Transport Layer | HI, port | 146 | | | 147 | SHIM Layer | HI | 148 | | | 149 | Network Layer | IP address | 150 +-------------------+-----------------------+ 152 Table 1 154 People prefer human-readable names when referring to network 155 entities. The most commonly used identifier in the User Interface is 156 the FQDN, but there are also other ways to name network entities. 157 The FQDN format is still the preferred UI level identifier in the 158 context of the native SHIM API. 160 In the current API, connection associations in the application layer 161 are uniquely distinguished by the source IP address, destination IP 162 address, source port, destination port, and protocol. HIP changes 163 this model by using HIT in the place of IP addresses. The HIP model 164 is further expanded in the native HIP API model by using ED instead 165 of HITs. Now, the application layer uses source ED, destination ED, 166 source port, destination port, and transport protocol type, to 167 distinguish between the different connection associations. 169 Basically, the difference between the application and transport layer 170 identifiers is that the transport layer uses HIs instead of EDs. The 171 TLI is named with source HI, destination HI, source port, and 172 destination port at the transport layer. 174 Correspondingly, the HIP layer uses HIs as identifiers. The HIP 175 security associations are based on source HI and destination HI 176 pairs. 178 The network layer uses IP addresses, i.e., locators, for routing 179 purposes. The network layer interacts with the HIP layer to exchange 180 information about changes in the local interfaces addresses and peer 181 addresses. 183 2.4. Socket Bindings 185 A HIP based SHIM socket is associated with one source and one 186 destination ED, along with their port numbers and protocol type. The 187 relationship between a socket and ED is a many-to-one one. Multiple 188 EDs can be associated with a single HI. Further, the source HI is 189 associated with a set of network interfaces at the local host. The 190 destination HI, in turn, is associated with a set of destination 191 addresses of the peer. The socket bindings are visualized in 192 Figure 2. 194 1 +---------+ * 1 +--------+ * * +-----------+ 195 +---+ Src EID +------+ Src HI +------+ Src Iface | 196 +--------+ * | +---------+ * 1 +--------+ +-----------+ 197 | HIP +------+ 198 | | 199 | Socket +------+ 200 +--------+ * | +---------+ * 1 +--------+ * * +-----------+ 201 +---+ Dst EID +------+ Dst HI +------+ Dst IP | 202 1 +---------+ * 1 +--------+ +-----------+ 204 Figure 2 206 The relationship between a source ED and a source HI is always a 207 many-to-one one. However, there are two refinements to the 208 relationship. First, a listening socket is allowed to accept 209 connections from all local HIs of the host. Second, the 210 opportunistic mode allows the base exchange to be initiated to an 211 unknown destination HI. In a way, the relationship between the local 212 ED and local HI is a many-to-undefined relationship momentarily in 213 both of the cases, but once the connection is established, the ED 214 will be permanently associated with a certain HI. 216 The DNS based endpoint discovery mechanism is illustrated in 217 Figure 3. The application calls the resolver (step a.) to resolve an 218 FQDN (step b.). The DNS server responds with a EID and a set of 219 locators (step c.). The resolver does not directly pass the EID and 220 the locators to the application, but sends them to the SHIM module 221 (step d.). Finally, the resolver receives an ED from the SHIM module 222 (step e.) and passes the ED to the application (step f.). 224 +----------+ 225 | | 226 | DNS | 227 | | 228 +----------+ 229 ^ | 230 b. | | c. 231 | v 232 +-------------+ a. +----------+ 233 | |----------->| | 234 | Application | | Resolver | 235 | |<-----------| | 236 +-------------+ f. +----------+ 237 ^ | 238 e. | | d. 239 | v 240 +----------+ 241 | | 242 | SHIM | 243 | | 244 +----------+ 246 Figure 3 248 The application can also receive multiple EDs from the resolver when 249 the FQDN is associated with multiple EIDs. The endpoint discovery 250 mechanism is still almost the same. The difference is that the DNS 251 returns a set of EIDs (along with the associated locators) to the 252 resolver. The resolver sends all of them to the SHIM module and 253 receives a set of EDs in return, each ED corresponding to a single 254 HI. Finally, the EDs are sent to the application. 256 3. Interface Syntax and Description 258 In this section, we describe the native SHIM API using the syntax of 259 the C programming language and present only the ``external'' 260 interfaces and data structures that are visible to the applications. 261 We limit the description to those interfaces and data structures that 262 are either modified or completely new, because the native SHIM API is 263 otherwise identical to the sockets API [1]. 265 3.1. Data Structures 267 We introduce a new protocol family, PF_SHIM, for the sockets API. 268 The AF_SHIM constant is an alias for it. The use of the PF_SHIM 269 constant is mandatory with the socket function if the native SHIM API 270 is to be used in the application. The PF_SHIM constant is given as 271 the first argument (domain) to the socket function. 273 The ED abstraction is realized in the sockaddr_ed structure, which is 274 shown in figure Figure 4. The family of the socket, ed_family, is 275 set to PF_SHIM. The port number ed_port is two octets and the ED 276 value ed_val is four octets. The ED value is just an opaque number 277 to the application. The application should not try to associate it 278 directly to a EID or even compare it to other ED values, because 279 there are separate functions for those purposes. The ED family is 280 stored in host byte order. The port and the ED value are stored in 281 network byte order. 283 struct sockaddr_ed { 284 unsigned short int ed_family; 285 in_port_t ed_port; 286 sa_ed_t ed_val; 287 } 289 Figure 4 291 The ed_val field is usually set by special native SHIM API functions, 292 which are described in the following section. However, three special 293 macros can be used to directly set a value into the ed_val field. 294 The macros are SHIM_ED_ANY, SHIM_ED_ANY_PUB and SHIM_ED_ANY_ANON. 295 They denote an ED value associated with a wildcard HI of any, public, 296 or anonymous type. They are useful to a ``server'' application that 297 is willing to accept connections to all of the HIs of the host. The 298 macros correspond to the sockets API macros INADDR_ANY and 299 IN6ADDR_ANY_INIT, but they are applicable on the SHIM layer. It 300 should be noted that only one process at a time can bind with the 301 SHIM_ED_*ANY macro on a certain port to avoid ambiguous bindings. 303 The native SHIM API has a new resolver function which is used for 304 querying both endpoint identifiers and locators. The resolver 305 introduces a new data structure, which is used both as the input and 306 output argument for the resolver. We reuse the existing resolver 307 datastructure shown in Figure 5. 309 struct addrinfo { 310 int ai_flags; /* e.g. AI_ED */ 311 int ai_family; /* e.g. PF_SHIM */ 312 int ai_socktype; /* e.g. SOCK_STREAM */ 313 int ai_protocol; /* usually just zero */ 314 size_t ai_addrlen; /* length of the endpoint */ 315 struct sockaddr *ai_addr; /* endpoint socket address */ 316 char *ai_canonname; /* canon. name of the host */ 317 struct addrinfo *ai_next; /* next endpoint */ 318 }; 320 Figure 5 322 In addrinfo structures, the family field is set to PF_SHIM when the 323 socket address structure contains an ED that refers to a SHIM 324 identifier, such as HI. 326 The flags in the addrinfo structure control the behavior of the 327 resolver and describe the attributes of the endpoints and locators: 329 o The flag AI_ED must be set, or otherwise the resolver does not 330 return EDs to guarantee that legacy applications won't break. 331 When AI_ED is set, the resolver returns a linked list which 332 contains first the sockaddr_ed structures for SHIM identifiers if 333 any was found. After that, any other type of socket addresses are 334 returned. 336 o When querying local identifiers, the AI_ED_ANON flag forces the 337 resolver to query only local anonymous identifiers. The default 338 action is first to resolve the public endpoints and then the 339 anonymous endpoints. 341 o Some applications may prefer configuring the locators manually and 342 can set the AI_ED_NOLOCATORS flag to prohibit the resolver from 343 resolving any locators. 345 o The AI_ED_ANY, AI_ED_ANY_PUB and AI_ED_ANY_ANON flags cause the 346 resolver to output only a single socket address containing an ED 347 that would be received using the corresponding SHIM_ED_*ANY macro. 349 o The getaddrinfo resolver does not return IP addresses belonging to 350 a SHIM rendezvous server unless AI_ED is defined. AI_ED_RVS, can 351 appear both in the input and output arguments of the resolver. In 352 the input, it can be used for resolving only rendezvous server 353 addresses. On the output, it denotes that the address is a 354 rendezvous rather than end-point address. 356 Application specified endpoint identifiers are essentially private 357 keys. To support application specified identifiers in the API, we 358 introduce new data structures for storing the private keys. The 359 private keys need an uniform format so that they can be easily used 360 in the API calls. The keys are stored in the endpoint structures as 361 shown in figure Figure 6. 363 struct endpoint { 364 se_length_t length; 365 se_family_t family; 366 }; 367 struct endpoint_hip { 368 se_length_t length; 369 se_family_t family; /* EF_HI in the case of HIP */ 370 se_hip_flags_t flags; 371 union { 372 struct hip_host_id host_id; 373 hit_t hit; 374 } id; 375 }; 377 Figure 6 379 The endpoint structure represents a generic endpoint and the 380 endpoint_hip structure represents a HIP specific endpoint. The 381 family field distinguishes whether the identifier is HIP or other 382 protocol related. The HIP endpoint is public by default unless 383 SHIM_ENDPOINT_FLAG_ANON flag is set in the structure to anonymize the 384 endpoint. The id union contains the HI in the host_id member in the 385 format specified in [3]. If the key is private, the material is 386 appended to the host_id with the length adjusted accordingly. The 387 flag SHIM_ENDPOINT_FLAG_PRIVATE is also set. The hit member of the 388 union is used only when the SHIM_ENDPOINT_FLAG_HIT flag is set. 390 3.2. Functions 392 In this section, some existing sockets API functions are reintroduced 393 along with their additions. Also, some new auxiliary functions are 394 defined. 396 3.2.1. Resolver Interface 398 The native SHIM API does not introduce changes to the interface 399 syntax of the primitive sockets API functions bind, connect, send, 400 sendto, sendmsg, recv, recvfrom, and recvmsg. However, the 401 application usually calls the functions with sockaddr_ed structures 402 instead of sockaddr_in or sockaddr_in6 structures. The source of the 403 sockaddr_ed structures in the native SHIM API is the resolver 404 function getaddrinfo [2] which is shown in Figure 7. 406 int getaddrinfo(const char *nodename, 407 const char *servname, 408 const struct addrinfo *hints, 409 struct addrinfo **res) 410 void free_addrinfo(struct addrinfo *res) 412 Figure 7 414 The getaddrinfo function takes the nodename, servname, and hints as 415 its input arguments. It places the result of the query into the res 416 argument. The return value is zero on success, or a non-zero error 417 value on error. The nodename argument specifies the host name to be 418 resolved; a NULL argument denotes the local host. The servname 419 parameter sets the port number to be set in the socket addresses in 420 the res output argument. Both the nodename and servname cannot be 421 NULL. 423 The output argument res is dynamically allocated by the resolver. 424 The application must free res argument with the free_addrinfo 425 function. The res argument contains a linked list of the resolved 426 endpoints. The input argument hints acts like a filter that defines 427 the attributes required from the resolved endpoints. For example, 428 setting the flag SHIM_ENDPOINT_FLAG_ANON in the hints forces the 429 resolver to return only anonymous endpoints in the output argument 430 res. A NULL hints argument indicates that any kind of endpoints are 431 acceptable. 433 3.2.2. Application Specified Identities 435 Application specified local and peer endpoints can be retrieved from 436 files using the function shown in Figure 8. The function 437 shim_endpoint_load_pem is used for retrieving a private or public key 438 from a given file filename. The file must be in PEM encoded format. 439 The result is allocated dynamically and stored into the endpoint 440 argument. The return value of the function is zero on success, or a 441 non-zero error value on failure. The result is deallocated with the 442 free system call. 444 int shim_endpoint_pem_load(const char *filename, 445 struct endpoint **endpoint) 447 Figure 8 449 The endpoint structure cannot be used directly in the sockets API 450 function calls. The application must convert the endpoint into an ED 451 first. Local endpoints are converted with the getlocaled function 452 and peer endpoints with getpeered function. The functions are 453 illustrated in Figure 9. 455 struct sockaddr_ed *getlocaled(const struct endpoint *endpoint, 456 const char *servname, 457 const struct addrinfo *addrs, 458 const struct if_nameindex *ifaces, 459 int flags) 460 struct sockaddr_ed *getpeered(const struct endpoint *endpoint, 461 const char *servname, 462 const struct addrinfo *addrs, 463 int flags) 465 Figure 9 467 The result of the conversion, an ED socket address, is returned by 468 both of the functions. A failure in the conversion causes a NULL 469 return value to be returned and the errno to be set accordingly. The 470 caller of the functions is responsible of freeing the returned socket 471 address structure. 473 The application can retrieve the endpoint argument e.g. with the 474 shim_endpoint_load_pem function. If the endpoint is NULL, the system 475 selects an arbitrary EID and associates it with the ED value of the 476 return value. 478 The servname argument is the service string. The function converts 479 it to a numeric port number and fills the port number into the 480 returned ED socket structure for the convenience of the application. 482 The addrs argument defines the initial IP addresses of the local host 483 or peer host. The argument is a pointer to a linked list of addrinfo 484 structures containing the initial addresses of the peer. The list 485 pointer can be obtained with a getaddrinfo [2] function call. A NULL 486 pointer indicates that the application trusts the host to already 487 know the locators of the peer. We recommend that a NULL pointer is 488 not given to the getpeered function to ensure reachability with the 489 peer. 491 The getlocaled function accepts also a list of network interface 492 indexes in the ifaces argument. The list can be obtained with the 493 if_nameindex [2] function call. A NULL list pointer indicates all 494 the interfaces of the local host. Both the IP addresses and 495 interfaces can be combined to select a specific address from a 496 specific interface. 498 The last argument is the flags. The following flags are valid only 499 for the getlocaled function: 501 o Flags SHIM_ED_REUSE_UID, SHIM_ED_REUSE_GID and SHIM_ED_REUSE_ANY 502 allow the EID (e.g. a large private key) to be reused for 503 processes with the same UID, GID or any UID as the calling 504 process. 506 o Flags SHIM_ED_IPV4 and SHIM_ED_IPV6 can be used for limiting the 507 address family scope of the local interface. 509 It should noticed that the SHIM_ED_ANY, SHIM_ED_ANY_PUB and 510 SHIM_ED_ANY_ANON macros can be implemented as calls to the getlocaled 511 call with a NULL endpoint, NULL interface, NULL address argument and 512 the flag corresponding to the macro name set. 514 3.2.3. Querying Endpoint Related Information 516 The getlocaled and getpeered functions have also their reverse 517 counterparts. Given an ED, the getlocaledinfo and getpeeredinfo 518 functions search for the EID (e.g. a HI) and the current set of 519 locators associated with the ED. The first argument is the ED to be 520 searched for. The functions write the results of the search, the HIs 521 and locators, to the rest of the function arguments. The function 522 interfaces are depicted in Figure 10. The caller of the functions is 523 responsible for freeing the memory reserved for the search results. 525 int getlocaledinfo(const struct sockaddr_ed *my_ed, 526 struct endpoint **endpoint, 527 struct addrinfo **addrs, 528 struct if_nameindex **ifaces) 529 int getpeeredinfo(const struct sockaddr_ed *peer_ed, 530 struct endpoint **endpoint, 531 struct addrinfo **addrs) 533 Figure 10 535 The getlocaledinfo and getpeeredinfo functions are especially useful 536 for an advanced application that receives multiple EDs from the 537 resolver. The advanced application can query the properties of the 538 EDs using getlocaledinfo and getpeeredinfo functions and select the 539 ED that matches the desired properties. 541 3.2.4. Socket Options 543 Reading and writing of SHIM socket options is done using getsockopt 544 and setsockopt functions. The first argument, the level, must be 545 specified as SOL_SHIM. 547 A number of SHIM socket option names are listed in Table 2. The 548 length of the option must be natural word size of the underlying 549 processor, typically 32 or 64 bits. The purpose of the option value 550 must be interpreted in context of the protocol specifications [3] 551 [4]. 553 Some of the socket options must be set before the hosts have 554 established connection. The implementation may refuse to accept the 555 option when there is already an existing connection and dynamic 556 renegotiation of the option is not possible. In addition, the SHIM 557 may return an error value if the corresponding SHIM protocol does not 558 support the given option. 560 Multihoming related socket options are defined in 561 draft-sugimoto-multihome-shim-api. It also specifies an event driven 562 API for application, which can be used for listening for changes in 563 locators. 565 +-----------------------------------+-------------------------------+ 566 | Socket Options | Purpose | 567 +-----------------------------------+-------------------------------+ 568 | SO_SHIM_CHALLENGE_SIZE | Puzzle challenge size | 569 | | | 570 | SO_SHIM_SHIM_TRANSFORMS | Integer array of the | 571 | | preferred SHIM transforms | 572 | | | 573 | SO_SHIM_ESP_TRANSFORMS | Integer array of the | 574 | | preferred ESP transforms | 575 | | | 576 | SO_SHIM_DH_GROUP_IDS | Integer array of the | 577 | | preferred Diffie-Hellman | 578 | | group IDs | 579 | | | 580 | SO_SHIM_SA_LIFETIME | Preferred IPsec SA lifetime | 581 | | in seconds | 582 | | | 583 | SO_SHIM_CTRL_RETRANS_INIT_TIMEOUT | SHIM initial retransmission | 584 | | timeout for SHIM control | 585 | | packets | 586 | | | 587 | SO_SHIM_CTRL_RETRANS_INTERVAL | SHIM retransmission interval | 588 | | in seconds | 589 | | | 590 | SO_SHIM_CTRL_RETRANS_ATTEMPTS | Number of retransmission | 591 | | attempts | 592 | | | 593 | SO_SHIM_AF_FAMILY | The preferred IP address | 594 | | family. The default family is | 595 | | AF_ANY. | 596 | | | 597 | SO_SHIM_PIGGYPACK | If set to one, HIP | 598 | | piggy-packing to TCP packets | 599 | | is used. Zero if | 600 | | piggy-packing must not be | 601 | | used. | 602 | | | 603 | SO_SHIM_OPPORTUNISTIC | Try SHIM in opportunistic | 604 | | mode when only the locators | 605 | | of the peer are known. | 606 | | | 607 | SO_SHIM_NAT_TRAVERSAL | Enable NAT traversal mode for | 608 | | SHIM. | 609 +-----------------------------------+-------------------------------+ 611 Table 2 613 4. IANA Considerations 615 No IANA considerations. 617 5. Security Considerations 619 To be done. 621 6. Acknowledgements 623 Jukka Ylitalo and Pekka Nikander have contributed many ideas, time 624 and effort to the native HIP API. Thomas Henderson, Kristian Slavov, 625 Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew 626 McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen and 627 Anthony Joseph have also provided valuable ideas and feedback. 629 7. References 631 7.1. Normative References 633 [1] Institute of Electrical and Electronics Engineers, "IEEE Std. 634 1003.1-2001 Standard for Information Technology - Portable 635 Operating System Interface (POSIX)", Dec 2001. 637 [2] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 638 Stevens, "Basic Socket Interface Extensions for IPv6", RFC 3493, 639 February 2003. 641 [3] Moskowitz, R., "Host Identity Protocol", draft-ietf-hip-base-06 642 (work in progress), June 2006. 644 [4] Nikander, P., "End-Host Mobility and Multihoming with the Host 645 Identity Protocol", draft-ietf-hip-mm-03 (work in progress), 646 March 2006. 648 [5] Henderson, T. and P. Nikander, "Using HIP with Legacy 649 Applications", draft-henderson-hip-applications-03 (work in 650 progress), May 2006. 652 7.2. Informative References 654 [6] Richardson, M. and B. Sommerfeld, "Requirements for an IPsec 655 API", draft-ietf-btns-ipsec-apireq-00 (work in progress), 656 April 2006. 658 Author's Address 660 Miika Komu 661 Helsinki Institute for Information Technology 662 Tammasaarenkatu 3 663 Helsinki 664 Finland 666 Phone: +358503841531 667 Fax: +35896949768 668 Email: miika@iki.fi 669 URI: http://www.iki.fi/miika/ 671 Full Copyright Statement 673 Copyright (C) The Internet Society (2006). 675 This document is subject to the rights, licenses and restrictions 676 contained in BCP 78, and except as set forth therein, the authors 677 retain all their rights. 679 This document and the information contained herein are provided on an 680 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 681 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 682 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 683 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 684 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 685 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 687 Intellectual Property 689 The IETF takes no position regarding the validity or scope of any 690 Intellectual Property Rights or other rights that might be claimed to 691 pertain to the implementation or use of the technology described in 692 this document or the extent to which any license under such rights 693 might or might not be available; nor does it represent that it has 694 made any independent effort to identify any such rights. Information 695 on the procedures with respect to rights in RFC documents can be 696 found in BCP 78 and BCP 79. 698 Copies of IPR disclosures made to the IETF Secretariat and any 699 assurances of licenses to be made available, or the result of an 700 attempt made to obtain a general license or permission for the use of 701 such proprietary rights by implementers or users of this 702 specification can be obtained from the IETF on-line IPR repository at 703 http://www.ietf.org/ipr. 705 The IETF invites any interested party to bring to its attention any 706 copyrights, patents or patent applications, or other proprietary 707 rights that may cover technology that may be required to implement 708 this standard. Please address the information to the IETF at 709 ietf-ipr@ietf.org. 711 Acknowledgment 713 Funding for the RFC Editor function is currently provided by the 714 Internet Society.