idnits 2.17.1 draft-ietf-hip-native-api-02.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 478. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 489. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 496. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 502. 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 313 has weird spacing: '... int ai_...' == Line 314 has weird spacing: '... int ai_...' == Line 315 has weird spacing: '... int ai_...' == Line 316 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 (July 7, 2007) is 6132 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: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-04) exists of draft-ietf-btns-c-api-00 == Outdated reference: A later version (-17) exists of draft-ietf-shim6-multihome-shim-api-02 ** Obsolete normative reference: RFC 4843 (Obsoleted by RFC 7343) Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 8 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: Informational Technology 5 Expires: January 8, 2008 July 7, 2007 7 Native Application Programming Interfaces for SHIM APIs 8 draft-ietf-hip-native-api-02 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 January 8, 2008. 38 Copyright Notice 40 Copyright (C) The IETF Trust (2007). 42 Abstract 44 This document defines 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 configure manually 49 mappings between upper layer identifiers and the corresponding 50 locators. Also, the API describes how to handle outbound connection 51 establishment where an application is unaware of the peer identifier 52 but knows the peer locator. 54 Table of Contents 56 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Design Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.1. Layering Model . . . . . . . . . . . . . . . . . . . . . . 4 62 3.2. Namespace Model . . . . . . . . . . . . . . . . . . . . . 4 63 3.3. Interaction with the Resolver . . . . . . . . . . . . . . 5 65 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6 66 4.1. Socket Family and Address Structure . . . . . . . . . . . 6 67 4.2. Resolver . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 73 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 75 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 78 Intellectual Property and Copyright Statements . . . . . . . . . . 12 80 1. Terminology 82 +---------+---------------------------------------------------------+ 83 | Term | Explanation | 84 +---------+---------------------------------------------------------+ 85 | ULID | Upper Layer IDentifier equals to the identity part of | 86 | | the identity/locator split. It is the identifier used | 87 | | by the application to name a peer for the transport | 88 | | layer. | 89 | Locator | Non-routable IPv4 or IPv6 address used at the lower | 90 | | layers | 91 | FQDN | Fully Qualified Domain Name | 92 | HIT | Host Identity Tag, a 100-bit hash of a public key with | 93 | | a 28 bit prefix | 94 | LSI | Locally Scope Identifier, a 32-bit local presentation | 95 | | of a public key | 96 +---------+---------------------------------------------------------+ 98 Table 1 100 2. Introduction 102 Host Identity Protocol proposes a new cryptographic namespace and a 103 new layer to the TCP/IP architecture. Applications can see these new 104 changes in the networking stacks with varying degrees of visibility. 105 [I-D.henderson-hip-applications] discusses the lowest levels of 106 visibility in which applications are either unaware of HIP. The HIP- 107 unaware applications use LSIs or HITs instead of IPv4 or IPv6 108 addresses. Such applications may be unaware of the locator bindings. 110 This document discusses about visibility of HIP to HIP-aware 111 applications. The applications are completely HIP aware and can 112 control the HIP layer and Host Identifiers. This document defines 113 C-based sockets API extensions for handling the bindings explicitly. 114 The extensions expose the identity-locator split to SHIM-aware 115 applications and it is up to the application, or a higher level 116 programming language, to manage the identities and locators. 118 The API extensions introduce a new socket address structure. The 119 structure requires a new address family, PF_SHIM, for sockets that 120 use HITs and locators explicitly. An application can also use the 121 family to detect SHIM support in the local host. 123 Hosts may accept incoming or initiate outgoing communications without 124 the knowledge of the identity of the peer. This document describes 125 also how to address this situation using late binding based on new 126 wildcards. 128 There are two related IETF documents that are define other related 129 API extensions. Multihoming related APIs are defined in 130 [I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes 131 and channel bindings are defined in [I-D.ietf-btns-c-api] 133 3. Design Model 135 In this section, the native SHIM API design is described from an 136 design point of view. We describe the layering and namespace model. 137 We conclude the discussion with a description of the resolver model. 139 3.1. Layering Model 141 The application layer accesses the transport layer via the socket 142 interface. The application layer uses the traditional TCP/IP IPv4 or 143 IPv6 interface, or the new native SHIM API interface provided by the 144 socket layer. The layering model is illustrated in Figure 1. For 145 simplicity, the IPsec layer has been excluded from the figure. 147 +--------------------------------+ 148 Application Layer | Application | 149 +----------+----------+----------+ 150 Socket Layer | IPv4 API | IPv6 API | SHIM API | 151 +----------+----+-----+----------+ 152 Transport Layer | TCP | UDP | 153 +---------------+----------------+ 154 SHIM Layer | HIP and other SHIMs | 155 +---------------+----------------+ 156 Network Layer | IPv4 | IPv6 | 157 +---------------+----------------+ 158 Link Layer | Ethernet | Etc | 159 +---------------+----------------+ 161 Figure 1 163 The SHIM layer is as a shim/wedge layer between the transport and 164 network layers. The datagrams delivered between the transport and 165 network layers are intercepted in the SHIM layer to see if the 166 datagrams are SHIM related and require SHIM intervention. 168 3.2. Namespace Model 170 The namespace model is shown in Table 2 from SHIM point of view. The 171 namespace identifiers are described in this section. 173 +-------------------+-------------------------+ 174 | Layer | Identifier | 175 +-------------------+-------------------------+ 176 | User Interface | FQDN | 177 | Application Layer | ULID, port and protocol | 178 | Transport Layer | ULID, port | 179 | SHIM Layer | ULID | 180 | Network Layer | Locator | 181 +-------------------+-------------------------+ 183 Table 2 185 User interfaces input human-readable names and translate them to 186 machine-readable names. In SHIM API, the ULID is a HIT when the 187 underlying protocol is HIP. The ULID is present at the application 188 layer and also transport layer checksum is calculated based on it. 189 The SHIM layer handles also ULIDs and translates them locators for 190 the network layer. 192 3.3. Interaction with the Resolver 194 Before an application can establish network communications, it must 195 translate a hostname to the corresponding identifier(s). DNS based 196 hostname-to-identifier translation is illustrated in Figure 2. The 197 application calls the resolver (step a.) to resolve an FQDN (step 198 b.). The DNS server responds with ULIDs and a set of locators (step 199 c.). The resolver may not directly pass the ULIDs and the locators 200 to the application, but may first inform to the SHIM module (steps d. 201 and e.). Finally, the resolver passes the ULIDs and locators to the 202 application (step f.). 204 +----------+ 205 | | 206 | DNS | 207 | | 208 +----------+ 209 ^ | 210 b. | | c. 211 | v 212 +-------------+ a. +----------+ 213 | |----------->| | 214 | Application | | Resolver | 215 | |<-----------| | 216 +-------------+ f. +----------+ 217 ^ | 218 | | 219 e. | | d. 220 | v 221 +----------+ 222 | | 223 | SHIM | 224 | | 225 +----------+ 227 Figure 2 229 In practise, the resolver functionality can implemented in different 230 ways. It may be implemented in existing resolver libraries or as an 231 DNS proxy. 233 4. API Syntax and Semantics 235 In this section, we describe the native SHIM API using the syntax of 236 the C programming language and present only the ``external'' 237 interfaces and data structures that are visible to the applications. 238 We limit the description to those interfaces and data structures that 239 are either modified or completely new, because the SHIM API is 240 otherwise identical to the sockets API [POSIX]. 242 4.1. Socket Family and Address Structure 244 We introduce a new protocol family, PF_SHIM, for the sockets API. 245 The AF_SHIM constant is an alias for it. The use of the PF_SHIM 246 constant is mandatory with the socket() function if the SHIM API is 247 to be used in the application. The PF_SHIM constant is given as the 248 first argument (domain) to the socket() function. 250 The ULIDs and locators are contained in the sockaddr_shim structure, 251 which is shown in Figure 3. The family of the socket, shim_family, 252 is set to PF_SHIM. The port number sins_port is two octets and the 253 sins_ulid is four octets. The ULID value is an IPv6 address. The 254 locator is an IPv6 address or IPv6-mapped address IPv4 address as 255 defined in - [RFC3493]. The family is stored in host byte order and 256 the ULID and locator are stored in network byte order. 258 typedef struct in6_addr shim_ulid_t; 259 typedef struct in6_addr shim_locator_t; 261 struct sockaddr_shim { 262 uint8_t sins_len; 263 uint8_t sins_family; 264 uint16_t sins_port; 265 shim_ulid_t sins_ulid; 266 shim_locator_t sins_locator; 267 uint64_t sins_flags; 268 } 270 Figure 3 272 The application usually sets the sins_ulid field using the resolver. 273 However, three special macros can be used to directly set a value 274 into the sins_ulid field. The macros are SHIM_ANY, SHIM_ANY_PUB and 275 SHIM_ANY_ANON. They denote an ULID value associated with a wildcard 276 ULID of any, public, or anonymous type. 278 In server applications, the SHIM_* macros accept incoming connections 279 to all of the ULID of the local host. The macros correspond to the 280 sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are 281 applicable at the SHIM layer. It should be noticed that only one 282 process at a time in a host can bind with the SHIM_*ANY macro to the 283 same port to avoid ambiguous bindings. 285 A client application can use the SHIM_ANY macro to establish a 286 connection when only the server locator (and not the ULID) is known 287 beforehand. 289 In both client and server based applications, the use of the 290 SHIM_ANY* macro accepts also non-SHIM based communications to 291 maximize backwards compatibility. When the application wants 292 enforces the use of SHIM-based communications with ORCHID prefix 293 [RFC4843], it sets the flag SHIM_FLAG_ONLY_ORCHID in sins_flags. 294 Alternatively, the application accepts both ORCHID and non-ORCHID- 295 based communications, but informs the difference e.g. to the user. 296 In this case, the application calls SHIM_IPV6_ADDR_IS_ORCHID macro 297 which inputs a pointer to a in6_addr and returns 1 when the address 298 has orchid prefix and 0 otherwise. 300 Applications can also implement access control using the ULIDs. In 301 such a case, the application can compare two ULIDs using memcmp() or 302 similar function. 304 4.2. Resolver 306 The SHIM API uses the getaddrinfo resolver function which the 307 application uses to query both ULIDs and locators. The resolver 308 introduces a new data structure, which is used both as the input and 309 output argument for the resolver. The data structure is illustrated 310 in Figure 4. 312 struct addrinfo { 313 int ai_flags; /* e.g. AI_SHIM */ 314 int ai_family; /* e.g. PF_SHIM */ 315 int ai_socktype; /* e.g. SOCK_STREAM */ 316 int ai_protocol; /* 0 or IPPROTO_HIP */ 317 size_t ai_addrlen; /* length of the endpoint */ 318 struct sockaddr *ai_addr; /* socket address */ 319 char *ai_canonname; /* canon. name of the host */ 320 struct addrinfo *ai_next; /* next endpoint */ 321 }; 323 Figure 4 325 In addrinfo structures, the family field is set to PF_SHIM when the 326 socket address structure contains an ULID that refers to ULID, such 327 as HIT. 329 The flag AI_SHIM must be set, or otherwise the resolver does not 330 return sockaddr_shim data structures to guarantee that legacy 331 applications do not break. Some applications may prefer configuring 332 the locators manually and can set the AI_SHIM_NOLOCATORS flag to 333 prohibit the getaddrinfo from resolving any locators. 335 The ai_family field is PF_SHIM with SHIM-specific addrinfo data 336 structures. 338 The protocol field is 0 when the getaddrinfo caller does not care 339 about the specific SHIM protocol to be used. The caller (or the 340 resolver) can set this field also to IPPROTO_HIP. 342 ai_addrlen is the size of the structure pointed by ai_addr. 344 The ai_addr points to a sockaddr_shim structure when the value of 345 ai_family is PF_SHIM. The resolver sets SHIM_RVS in sins_flags of 346 the when the locator belongs to a rendezvous server 347 [I-D.ietf-hip-dns]. 349 The SHIM API does not introduce changes to the interface syntax of 350 the existing sockets API functions, such as bind(), connect(), 351 send(), sendto(), sendmsg(), recv(), recvfrom(), and recvmsg(). 352 However, the SHIM-aware application usually passes the functions a 353 sockaddr_shim structure instead of a sockaddr_in or sockaddr_in6 354 structure. A SHIM-aware application either creates the sockaddr_shim 355 structures manually or obtains them from the resolver. The 356 getaddrinfo resolver [RFC3493] is shown in Figure 5. 358 int getaddrinfo(const char *nodename, 359 const char *servname, 360 const struct addrinfo *hints, 361 struct addrinfo **res) 362 void free_addrinfo(struct addrinfo *res) 364 Figure 5 366 As described in [RFC3493], the getaddrinfo function takes the 367 nodename, servname, and hints as its input arguments. It places the 368 result of the query into the res argument. The return value is zero 369 on success, or a non-zero error value on error. The nodename 370 argument specifies the host name to be resolved; a NULL argument 371 denotes the local host. The servname parameter declares the port 372 number to be set in the socket addresses in the res output argument. 373 Both the nodename and servname cannot be NULL. 375 The input argument hints acts like a filter that defines the 376 attributes required from the resolved endpoints. For example, the 377 resolver returns only anonymous endpoints in the output argument res 378 when the application sets the ai_addr pointer of hints to point to a 379 sockaddr_shim structure with sins_ulid filled with SHIM_ANY_ANON. A 380 NULL hints argument indicates that any kind of endpoints are 381 acceptable. 383 The output argument res is dynamically allocated by the resolver. 384 The application must free res argument with the free_addrinfo 385 function. The res argument contains a linked list of the resolved 386 endpoints. The linked list contains sockaddr_shim structures only 387 when the input argument has the AI_SHIM flag set. When the resolver 388 finds SHIM identifiers, it inserts them to the front of the list. 390 Resolving of a hostname may result in multiple locators associated to 391 a single ULID, but the sockaddr_shim structure contains only a single 392 ULID-locator pair. The resolver handles this by repeating the ULD as 393 many time as needed. For example, let us consider a case where the 394 resolver finds an ULID that is associated to two locators. In such a 395 case, the resolver outputs two sockaddr_shim structures with the same 396 ULID but different locators. 398 5. IANA Considerations 400 No IANA considerations. 402 6. Security Considerations 404 To be done. 406 7. Acknowledgements 408 Jukka Ylitalo and Pekka Nikander have contributed many ideas, time 409 and effort to the HIP API. Thomas Henderson, Kristian Slavov, Julien 410 Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor, 411 Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Anthony 412 Joseph, Teemu Koponen and Juha-Matti Tapio have also provided 413 valuable ideas and feedback. Thanks for the APPS area folks, 414 Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and 415 especially Keith Moore for comments. 417 8. Normative References 419 [I-D.henderson-hip-applications] 420 Henderson, T. and P. Nikander, "Using HIP with Legacy 421 Applications", draft-henderson-hip-applications-03 (work 422 in progress), May 2006. 424 [I-D.ietf-btns-c-api] 425 Komu, M., "IPsec Application Programming Interfaces", 426 draft-ietf-btns-c-api-00 (work in progress), June 2007. 428 [I-D.ietf-hip-dns] 429 Nikander, P. and J. Laganier, "Host Identity Protocol 430 (HIP) Domain Name System (DNS) Extensions", 431 draft-ietf-hip-dns-09 (work in progress), April 2007. 433 [I-D.ietf-shim6-multihome-shim-api] 434 Komu, M., "Socket Application Program Interface (API) for 435 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-02 436 (work in progress), March 2007. 438 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 439 Std. 1003.1-2001 Standard for Information Technology - 440 Portable Operating System Interface (POSIX)", Dec 2001. 442 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 444 Stevens, "Basic Socket Interface Extensions for IPv6", 445 RFC 3493, February 2003. 447 [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix 448 for Overlay Routable Cryptographic Hash Identifiers 449 (ORCHID)", RFC 4843, April 2007. 451 Author's Address 453 Miika Komu 454 Helsinki Institute for Information Technology 455 Tammasaarenkatu 3 456 Helsinki 457 Finland 459 Phone: +358503841531 460 Fax: +35896949768 461 Email: miika@iki.fi 462 URI: http://www.iki.fi/miika/ 464 Full Copyright Statement 466 Copyright (C) The IETF Trust (2007). 468 This document is subject to the rights, licenses and restrictions 469 contained in BCP 78, and except as set forth therein, the authors 470 retain all their rights. 472 This document and the information contained herein are provided on an 473 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 474 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 475 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 476 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 477 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 478 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 480 Intellectual Property 482 The IETF takes no position regarding the validity or scope of any 483 Intellectual Property Rights or other rights that might be claimed to 484 pertain to the implementation or use of the technology described in 485 this document or the extent to which any license under such rights 486 might or might not be available; nor does it represent that it has 487 made any independent effort to identify any such rights. Information 488 on the procedures with respect to rights in RFC documents can be 489 found in BCP 78 and BCP 79. 491 Copies of IPR disclosures made to the IETF Secretariat and any 492 assurances of licenses to be made available, or the result of an 493 attempt made to obtain a general license or permission for the use of 494 such proprietary rights by implementers or users of this 495 specification can be obtained from the IETF on-line IPR repository at 496 http://www.ietf.org/ipr. 498 The IETF invites any interested party to bring to its attention any 499 copyrights, patents or patent applications, or other proprietary 500 rights that may cover technology that may be required to implement 501 this standard. Please address the information to the IETF at 502 ietf-ipr@ietf.org. 504 Acknowledgment 506 Funding for the RFC Editor function is provided by the IETF 507 Administrative Support Activity (IASA).