idnits 2.17.1 draft-ietf-zeroconf-zmaap-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 234 has weird spacing: '...ockaddr sr_st...' == Line 235 has weird spacing: '...ockaddr sr_en...' == Line 252 has weird spacing: '...ed long ld_i...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (6 June 2001) is 8358 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 ---------------------------------------------------------------------------- == Missing Reference: '20' is mentioned on line 231, but not defined == Outdated reference: A later version (-02) exists of draft-ietf-zeroconf-zmaap-01 ** Obsolete normative reference: RFC 3066 (ref. '5') (Obsoleted by RFC 4646, RFC 4647) Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETWORK Working Group Erik Guttman 3 INTERNET-DRAFT Sun Microsystems 4 Category: Informational 5 6 June 2001 6 Expires in six months 8 An API for the Zeroconf Multicast Address Allocation Protocol (ZMAAP) 9 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 Copyright Notice 34 Copyright (C) The Internet Society (2000). All Rights Reserved. 36 Abstract 38 Today, with the rapid rise of home networking, there is an increasing 39 need for auto-configuration mechanisms. This document specifies an 40 api to be used for applications which require multicast addresses on 41 small networks without a multicast address allocation server. 43 1.0 Introduction 45 The Zeroconf Multicast Address Allocation Protocol (ZMAAP) is defined 46 elsewhere [1]. This document specifies an application programmer 47 interface (API) which builds upon the foundation of the Abstract API 48 for Multicast Address Allocation [2]. Specifically, there are 49 additional requirements posed by ZMAAP which are not considered in 50 RFC 2771: 52 - Shared ownership of allocations (renewal and defense) 53 - Notification of conflicts with specific allocations 54 - Allocations all start immediately and continue until 55 they are released. This is a simplified API which 56 does not allow applications to manage allocations 57 via absolute times. 59 It should be transperant to the API whether the allocations are done 60 using ZMAAP, MADCAP [3] or some other mechanism. 62 In this document, the key words "MAY", "MUST, "MUST NOT", 63 "optional", "recommended", "SHOULD", and "SHOULD NOT", are to be 64 interpreted as described in [4]. 66 2.0 Abstract ZMAAP API Definition 68 The ZMAAP API provides the functions described in the Abstract 69 Multicast Address Allocation API [2], with a few additions. 71 2.1 Request Enumeration of Available Scopes 73 Scopes available for allocation are returned. 75 This corresponds to the Abstract API get_multicast_addr_scopes(). 77 Parameters: the address family. 79 Return value: Scope Records, each of which contains: 81 * the address family 82 * the start and end address of the range 83 * a suggested transmission IPv4 TTL or IPv6 Hop Count for 84 messages multicast into the scope range. 86 Mini-MAAS behavior: None. 88 2.2 Allocation 90 The application specifies which scope to allocate from and how many 91 addresses are needed. 93 This corresponds to the Abstract API alloc_multicast_addr(). 95 Parameters: 97 * Scope Record: Which scope to use. 99 * Integer: How many addresses to attempt to allocate. 100 * Integer: How many milliseconds to block before giving up, if 101 allocation is not successful. 103 Return value: No result, or a Lease Descriptor containing: 105 * An address range 106 * A lease identifier (this is useful information for including 107 in session announcements, see [1], Appendix B). 109 Mini-MAAS behavior: 111 The mini-MAAS attempts to claim the address(es). It will give 112 up after the time allotted for allocation has expired. If it 113 succeeds, it will enter the allocation into the allocation 114 record. The mini-MAAS will select a lease duration. Before 115 this lease duration expires, the mini-MAAS send an addtional AIU 116 message - effectively renewing the lease. 118 2.3 Release 120 An application indicates it is no longer interested in an allocation. 122 This corresponds to the Abstract API deallocate_multicast_addr(). 124 Parameters: Lease Descriptor. 126 Return value: Success or Failure (ie. bad parameter). 128 Mini-MAAS behavior: 130 The allocation is removed from the allocation record. 132 2.4 Defense 134 An application, having discovered a session (see [1], Appendix B) 135 wishes to participate in defense of a multicast address. 137 This is a new interface, not present in the Abstract API. 139 Parameters: Lease Descriptor. 141 Return value: Success or Failure (bad parameter or bad descriptor). 143 Mini-MAAS behavior: 145 The mini-MAAS adds the lease descriptor to its allocation 146 record. 148 2.5 Conflict Notification. 150 An application registers its desire to be notified if a conflict is 151 discovered for a given address allocation. This address allocation 152 could be made by the application (using the Allocation interface) or 153 it may have be a discovered session (see [1], Appendix B). 155 This is a new interface, not present in the Abstract API. 157 Parameters: 159 * Lease Descriptor. 160 * Opaque User Parameter 161 * Callback function or the equivalent. The parameters to this 162 function will be the Lease Descriptor which has a conflict 163 and the Opaque User Parameter. 165 Return value: Success or Failure (bad parameter or bad descriptor). 167 Mini-MAAS behavior: 169 Mini-MAASs process all incoming AIU messages. AIUs are sent 170 initially upon allocation and periodically (in order to prevent 171 the lifetime of the lease expiring). If an AIU received 172 conflicts with an entry in the allocation record, the record 173 MUST be removed (see [1] section 4.4.4). 175 The mini-MAAS issues the callback function associated with the 176 lease descriptor to all applications which have requested 177 notification of a conflict. This notification occurs once (that 178 is, only the first time there is a conflict, not every time). 179 The notification callback function is likely to be made in the 180 context of a different thread than the calling application. 182 2.6 Scope Name Query 184 The application can request the name of a scope by specifying the 185 scope record and the language in which to return the string. If the 186 name cannot be returned in the requested language, the name in the 187 default language is supplied. 189 This corresponds to the Abstract API named get_scope_name(). 191 Parameters: 193 * Scope Record: Get the name for this scope. 194 * String: Language Tag [5]. This is the language of the scope 195 name to return. 197 Return Value: 199 * a string identifier describing the address scope. 200 * a Language Tag [5] which specifies the language for the scope 201 identifier. 203 2.7 Abstract API Interfaces not supported 205 The ZMAAP API is a simplified subset of the API presente din RFC 206 2771. It does not include support for: 208 - change_multicast_addr_start_time() 209 - change_multicast_addr_lifetime() 211 All ZMAAP API allocations are considered to be continual, until 212 released. A mini-MAAS associates a lifetime with the 213 registration, but this is outside of the application's control. 215 - get_scope_netsting_state() 216 - get_larger_scopes() 217 - get_smaller_scopes() 219 ZMAAP supported scopes are simple at the present time, not 220 nested. 222 3.0 Programming Language Specific Concrete APIs 224 This includes utilities required for the language specific API, ie., 225 memory management functions for the C language API. 227 4.0 ZMAAP API for C 229 4.1 Definitions 231 Data elements in the structures below use types defined in [20]. 233 typedef struct scoperec { 234 struct sockaddr sr_start_addr; /* Scope's first address */ 235 struct sockaddr sr_end_addr; /* Scope's final address */ 236 int sr_scope; /* Scope ID, [1] Section 4.2.2 237 */ 238 int sr_ttl; /* Suggested TTL to use */ 239 } scope_record; 241 The scope_record includes a range of addresses and a TTL which hosts 242 SHOULD use when sending messages to addresses in that scope. For 243 example, datagrams sent to link-local scopes should set the IPv4 TTL 244 (or IPv6 Hop Count field) to 1. This will reduce the chance that 245 these datagrams will be forwarded off-link by routers, incorrectly. 247 typedef struct leasedesc { 248 int ld_addr_family; /* IPv4 = 1, IPv6 = 2 */ 249 struct sockaddr ld_start_addr; /* First address allocated */ 250 struct sockaddr ld_end_addr; /* Final address allocated */ 251 struct sockaddr ld_interface; /* The associated interface */ 252 unsigned long ld_id; /* The lease identifier */ 253 } lease_desc; 255 The lease_desc contains information about an individual address 256 allocation. In some cases, these are returned by the API. In others 257 the application forms these on the basis of session discovery. (See 258 appendix B). 260 typedef void zmaap_cb(lease_desc ld, void *pv); 262 A function with a prototype matching zmaap_cb is registered using the 263 zmaap_register() function below. The callback function is evoked by 264 the API (in a distinct thread) if there is an allocation conflict 265 detected in the address range of the registered lease descriptor. 266 The parameters to this function are described under zmaap_register(), 267 below. 269 typedef enum { OK=0, LEASE_CONFLICT=-1, TIMEOUT=-2, BAD_PARAM=-3 } 270 ZMErrCode; 272 LEASE_CONFLICT is returned if a lease descriptor parameter conflicts 273 with another, existing multicast allocation or fails to correspond to 274 an entry in the allocation record. 276 TIMEOUT is returned if the attempt to verify the validity of the 277 lease times out before finding determining if it corresponded or was 278 in conflict with a prior address allocation. 280 4.2 Functions 282 scope_record * zmaap_enumerate_scopes(int family); 284 Parameters: family IPv4 = 1, IPv6 = 2. No other values are 285 allowed. 287 Returns: An array of scope_records. The caller frees them using 288 zmaap_free(). An improper value for family results in a NULL 289 return value. 291 lease_desc * zmaap_allocate(scope_record *sr, struct sockaddr ifa, 292 int num, int msec); 294 Parameters: 295 sr A scope record returned using zmaap_enumerate_scopes(); 296 ifa The interface on which to make the allocation. 297 num The number of addresses requested. 298 msec The maximum number of milliseconds to attempt allocation. 300 Returns: NULL if no addresses can be obtained before the allotted 301 time expires of if the parameters are bad. The lease_desc 302 returned must be freed using zmaap_free. 304 int zmaap_release(lease_desc ld); 306 Parameters: 307 ld The lease descriptor to remove from the allocation record. 309 Returns: ZMErrCode. 311 int zmaap_defense(lease_desc ld, int msec); 313 Parameters: 314 ld The lease descriptor of the multicast allocation to defend. 315 msec The number of seconds to block while verifying the lease to 316 defend is valid. 318 Returns: ZMErrCode 320 int zmaap_register(lease_desc ld, void *pv, zmaap_cb *pf, int msec); 322 Parameters: 323 ld The lease descriptor of the allocation app wants to be 324 notified of if a conflict occurs. 325 pv The opaque user parameter present in the callback 326 function. 327 pf The user supplied callback function. 328 msec The maximum number of milliseconds to attempt to verify ld. 330 Returns: ZMErrCode 332 void zmaap_scope_name(scope_record sr, const char * tagq, char 333 **name, char **taga); 335 Parameters: 336 sr The scope to get the name of. 337 tagq The language tag desired. If NULL use default. 338 name Will point to an allocated buffer with the scope's name. 339 taga Will point to an allocated buffer with the name's language 340 tag. 342 Returns: This routine always succeeds. The strings allocated must 343 be freed with free(). 345 void zmaap_free(void *mem); 347 Parameters: 348 mem Either an array of scope_records or a lease_desc allocated 349 by the zmaap API. 351 5. ZMAAP API for Java 353 The Java API uses definitions from JDK 1.4 [6]. 355 package org.zeroconf.zmaap; 357 import java.net.*; 358 import java.util.*; 360 public class ScopeRecord { 362 public SocketAddress iaStart; // The start address of the scope 363 range. 364 public SocketAddress iaEnd; // The end address of the scope 365 range. 366 public int ttl; // The recommended TTL to use in 367 scope. 368 public int scopeid; // See [1], Section 4.2.2 370 } 372 public BadLeaseException extends Exception { 374 public BadLeaseException(String msg); 375 public BadLeaseException(); 377 } 379 public ScopeName { 381 public Locale locale; // The Locale of the scope name 382 public String scopename; 384 } 386 public class LeaseDesc { 388 public SocketAddress start; // The allocation's start address. 389 public SocketAddress end; // The allocation's end address. 390 public NetworkInterface interf; // The interface for the 391 allocation. 393 public int id; // The allocation's lease ID. 395 } 397 public class ConflictListener implements EventListener { 399 /** 400 * This event occurs when a conflict arises with an allocation. 401 * The ConflictListener is registered with ZMAAP.register(). 402 * 403 * @param alloc This is the allocation which has a conflict. 404 * @param o This is an opaque object registered with ZMAAP. 405 */ 406 public void conflictEvent(LeaseDesc alloc, Object o); 408 } 410 public class ZMAAP { 412 /** 413 * @return All scopes available for allocation. 414 */ 415 static ScopeRecord[] availableScopes(); 417 /** 418 * Return the name associated with a scope, in requested language. 419 * If the requested language is not supported, the default language 420 * will be used. 421 * 422 * @param locale The locale requested for the scope name. 423 * @param scope The scope whose name is sought. 424 * 425 * @return The name associated with the scope. 426 */ 427 static ScopeName queryScopeName(Locale locale, ScopeRecord scope); 429 /** 430 * Allocate a range of multicast addresses. This method will 431 * only return after it is successful or times out. 432 * 433 * @param sr A ScopeRecord obtained using availableScopes(). 434 * @param num The number of addresses requested. 435 * @param msec Maximum number of milliseconds to attempt to 436 * allocate the addresses. 437 * @return An allocation. 438 * @exception java.io.InterruptedIOException 439 * If ZMAAP.allocate() runs out of time. 440 * @exception java.lang.IllegalArgumentException 441 * If the parameters are unacceptable. 442 */ 443 static LeaseDesc allocate(ScopeRecord sr, int num, int msec) 444 throws InterruptedIOException, IllegalArgumentException; 446 /** 447 * Stop defending an address allocation. This will happen 448 * anyway if this JVM exits. 449 * 450 * @param ld This must represent an allocation which has either 451 * been created with ZMAAP.allocate() or is being 452 * defended, using ZMAAP.defend(). 453 * @exception org.zeroconf.BadLeaseException 454 * If the allocation in the parameter does not 455 * correspond to a LeaseDesc this ZMAAP instance 456 * is currently defending. 457 */ 458 static void release(LeaseDesc ld) 459 throws BadLeaseException; 461 /** 462 * Participate in defense of an allocation. This method 463 * will only return when successful or it times out. 464 * 465 * @param ld This allocation must correspond to one which 466 * has been made by calling ZMAAP.allocate() or 467 * which has been discovered by some other means, 468 * such as the Session Announcement Protocol, 469 * RFC 2974. If the allocation is unknown to the 470 * ZMAAP object, it will attempt to validate its 471 * existence. 472 * 473 * @param ms The maximum time in milliseconds to attempt to 474 * validate the lease descriptor before giving up. 475 * @exception java.io.InterruptedIOException 476 * If validating the allocation runs out of time. 477 * @exception org.zeroconf.BadLeaseException 478 * If the allocation does not correspond to an 479 * existing, defended address. 480 * @exception java.lang.IllegalArgumentException 481 If the ms argument is <= 0. 482 */ 483 static void defend(LeaseDesc ld, int ms) 484 throws InterruptedIOException, BadLeaseException, 485 IllegalArgumentException; 486 /** 487 * Request notification if an allocation conflict occurs. 488 * Note that a nonexistent allocation may be passed to this 489 * method in the LeaseDesc parameter - its validity will 490 * not necessarily be checked - though conflicts with it 491 * will (eventually) cause a notification to occur. 492 * 493 * @param cl The conflictEvent method of this object will 494 * be called on a separate thread if a conflict 495 * is detected. 496 * @param ld The allocation for which the ZMAAP object 497 * must detect conflicts. 498 * @param o An opaque user parameter which will be passed 499 * to the ConflictListener.conflictEvent method. 500 * @param ms The maximum time in milliseconds to attempt to 501 * validate the lease descriptor before giving up. 502 * @exception java.lang.IllegalArguement 503 * If cl is null. 504 * @exception org.zeroconf.BadLeaseException 505 * If the allocation does not correspond to an 506 * existing, defended address. 507 * @exception java.io.InterruptedIOException 508 * If validating the allocation runs out of time. 509 */ 510 static void register(ConflictListener cl, LeaseDesc ld, Object o, 511 int ms) 512 throws IllegalArgumentException, BadLeaseException, 513 InterruptedIOException; 514 } 516 References 518 [1] Catrina, O., et. al., "Zeroconf Multicast Address Allocation 519 Protocol (ZMAAP)", draft-ietf-zeroconf-zmaap-01.txt. A work in 520 progress. 522 [2] Finlayson, R., "An Abstract API for Multicast Address 523 Allocation", RFC 2771, February 2000. 525 [3] Hanna, S., Patel, B., and M. Shah, "Multicast Address Dynamic 526 Client Allocation Protocol (MADCAP)", RFC 2730, December 1999. 528 [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement 529 Levels", BCP 14, RFC 2119, March 1997. 531 [5] Alvestrand, H. "Tags for the Identification of Languages", RFC 532 3066, January 2001. 534 [6] Java Development Kit, version 1.4.0, Beta, Documentation, 535 http://www.javasoft.com/j2se/1.4/#documentation 537 Acknowledgments 539 Dave Thaler's input assisted in preparing this specification. 541 Authors' Addresses 543 Erik Guttman 544 Sun Microsystems 545 Eichhoelzelstr. 7 546 74915 Waibstadt Germany 548 Phone: +49 172 865 5497 549 Email: erik.guttman@sun.com 551 Full Copyright Statement 553 Copyright (C) The Internet Society (1999). All Rights Reserved. 555 This document and translations of it may be copied and furnished to 556 others, and derivative works that comment on or otherwise explain it 557 or assist in its implementation may be prepared, copied, published 558 and distributed, in whole or in part, without restriction of any 559 kind, provided that the above copyright notice and this paragraph are 560 included on all such copies and derivative works. However, this 561 document itself may not be modified in any way, such as by removing 562 the copyright notice or references to the Internet Society or other 563 Internet organizations, except as needed for the purpose of 564 developing Internet standards in which case the procedures for 565 copyrights defined in the Internet Standards process must be 566 followed, or as required to translate it into languages other than 567 English. 569 The limited permissions granted above are perpetual and will not be 570 revoked by the Internet Society or its successors or assigns. 572 This document and the information contained herein is provided on an 573 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 574 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 575 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 576 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 577 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 579 Acknowledgement 581 Funding for the RFC Editor function is currently provided by the 582 Internet Society.