NETWORK Working Group Erik Guttman INTERNET-DRAFT Sun Microsystems Category: Informational 6 June 2001 Expires in six months An API for the Zeroconf Multicast Address Allocation Protocol (ZMAAP) Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract Today, with the rapid rise of home networking, there is an increasing need for auto-configuration mechanisms. This document specifies an api to be used for applications which require multicast addresses on small networks without a multicast address allocation server. 1.0 Introduction The Zeroconf Multicast Address Allocation Protocol (ZMAAP) is defined elsewhere [1]. This document specifies an application programmer interface (API) which builds upon the foundation of the Abstract API for Multicast Address Allocation [2]. Specifically, there are additional requirements posed by ZMAAP which are not considered in Guttman, E. Expires: 6 December 2001 [Page 1] Internet Draft ZMAAP API June 2001 RFC 2771: - Shared ownership of allocations (renewal and defense) - Notification of conflicts with specific allocations - Allocations all start immediately and continue until they are released. This is a simplified API which does not allow applications to manage allocations via absolute times. It should be transperant to the API whether the allocations are done using ZMAAP, MADCAP [3] or some other mechanism. In this document, the key words "MAY", "MUST, "MUST NOT", "optional", "recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as described in [4]. 2.0 Abstract ZMAAP API Definition The ZMAAP API provides the functions described in the Abstract Multicast Address Allocation API [2], with a few additions. 2.1 Request Enumeration of Available Scopes Scopes available for allocation are returned. This corresponds to the Abstract API get_multicast_addr_scopes(). Parameters: the address family. Return value: Scope Records, each of which contains: * the address family * the start and end address of the range * a suggested transmission IPv4 TTL or IPv6 Hop Count for messages multicast into the scope range. Mini-MAAS behavior: None. 2.2 Allocation The application specifies which scope to allocate from and how many addresses are needed. This corresponds to the Abstract API alloc_multicast_addr(). Parameters: * Scope Record: Which scope to use. Guttman, E. Expires: 6 December 2001 [Page 2] Internet Draft ZMAAP API June 2001 * Integer: How many addresses to attempt to allocate. * Integer: How many milliseconds to block before giving up, if allocation is not successful. Return value: No result, or a Lease Descriptor containing: * An address range * A lease identifier (this is useful information for including in session announcements, see [1], Appendix B). Mini-MAAS behavior: The mini-MAAS attempts to claim the address(es). It will give up after the time allotted for allocation has expired. If it succeeds, it will enter the allocation into the allocation record. The mini-MAAS will select a lease duration. Before this lease duration expires, the mini-MAAS send an addtional AIU message - effectively renewing the lease. 2.3 Release An application indicates it is no longer interested in an allocation. This corresponds to the Abstract API deallocate_multicast_addr(). Parameters: Lease Descriptor. Return value: Success or Failure (ie. bad parameter). Mini-MAAS behavior: The allocation is removed from the allocation record. 2.4 Defense An application, having discovered a session (see [1], Appendix B) wishes to participate in defense of a multicast address. This is a new interface, not present in the Abstract API. Parameters: Lease Descriptor. Return value: Success or Failure (bad parameter or bad descriptor). Mini-MAAS behavior: The mini-MAAS adds the lease descriptor to its allocation record. Guttman, E. Expires: 6 December 2001 [Page 3] Internet Draft ZMAAP API June 2001 2.5 Conflict Notification. An application registers its desire to be notified if a conflict is discovered for a given address allocation. This address allocation could be made by the application (using the Allocation interface) or it may have be a discovered session (see [1], Appendix B). This is a new interface, not present in the Abstract API. Parameters: * Lease Descriptor. * Opaque User Parameter * Callback function or the equivalent. The parameters to this function will be the Lease Descriptor which has a conflict and the Opaque User Parameter. Return value: Success or Failure (bad parameter or bad descriptor). Mini-MAAS behavior: Mini-MAASs process all incoming AIU messages. AIUs are sent initially upon allocation and periodically (in order to prevent the lifetime of the lease expiring). If an AIU received conflicts with an entry in the allocation record, the record MUST be removed (see [1] section 4.4.4). The mini-MAAS issues the callback function associated with the lease descriptor to all applications which have requested notification of a conflict. This notification occurs once (that is, only the first time there is a conflict, not every time). The notification callback function is likely to be made in the context of a different thread than the calling application. 2.6 Scope Name Query The application can request the name of a scope by specifying the scope record and the language in which to return the string. If the name cannot be returned in the requested language, the name in the default language is supplied. This corresponds to the Abstract API named get_scope_name(). Parameters: * Scope Record: Get the name for this scope. * String: Language Tag [5]. This is the language of the scope name to return. Return Value: Guttman, E. Expires: 6 December 2001 [Page 4] Internet Draft ZMAAP API June 2001 * a string identifier describing the address scope. * a Language Tag [5] which specifies the language for the scope identifier. 2.7 Abstract API Interfaces not supported The ZMAAP API is a simplified subset of the API presente din RFC 2771. It does not include support for: - change_multicast_addr_start_time() - change_multicast_addr_lifetime() All ZMAAP API allocations are considered to be continual, until released. A mini-MAAS associates a lifetime with the registration, but this is outside of the application's control. - get_scope_netsting_state() - get_larger_scopes() - get_smaller_scopes() ZMAAP supported scopes are simple at the present time, not nested. 3.0 Programming Language Specific Concrete APIs This includes utilities required for the language specific API, ie., memory management functions for the C language API. 4.0 ZMAAP API for C 4.1 Definitions Data elements in the structures below use types defined in [20]. typedef struct scoperec { struct sockaddr sr_start_addr; /* Scope's first address */ struct sockaddr sr_end_addr; /* Scope's final address */ int sr_scope; /* Scope ID, [1] Section 4.2.2 */ int sr_ttl; /* Suggested TTL to use */ } scope_record; The scope_record includes a range of addresses and a TTL which hosts SHOULD use when sending messages to addresses in that scope. For example, datagrams sent to link-local scopes should set the IPv4 TTL (or IPv6 Hop Count field) to 1. This will reduce the chance that these datagrams will be forwarded off-link by routers, incorrectly. Guttman, E. Expires: 6 December 2001 [Page 5] Internet Draft ZMAAP API June 2001 typedef struct leasedesc { int ld_addr_family; /* IPv4 = 1, IPv6 = 2 */ struct sockaddr ld_start_addr; /* First address allocated */ struct sockaddr ld_end_addr; /* Final address allocated */ struct sockaddr ld_interface; /* The associated interface */ unsigned long ld_id; /* The lease identifier */ } lease_desc; The lease_desc contains information about an individual address allocation. In some cases, these are returned by the API. In others the application forms these on the basis of session discovery. (See appendix B). typedef void zmaap_cb(lease_desc ld, void *pv); A function with a prototype matching zmaap_cb is registered using the zmaap_register() function below. The callback function is evoked by the API (in a distinct thread) if there is an allocation conflict detected in the address range of the registered lease descriptor. The parameters to this function are described under zmaap_register(), below. typedef enum { OK=0, LEASE_CONFLICT=-1, TIMEOUT=-2, BAD_PARAM=-3 } ZMErrCode; LEASE_CONFLICT is returned if a lease descriptor parameter conflicts with another, existing multicast allocation or fails to correspond to an entry in the allocation record. TIMEOUT is returned if the attempt to verify the validity of the lease times out before finding determining if it corresponded or was in conflict with a prior address allocation. 4.2 Functions scope_record * zmaap_enumerate_scopes(int family); Parameters: family IPv4 = 1, IPv6 = 2. No other values are allowed. Returns: An array of scope_records. The caller frees them using zmaap_free(). An improper value for family results in a NULL return value. lease_desc * zmaap_allocate(scope_record *sr, struct sockaddr ifa, int num, int msec); Parameters: sr A scope record returned using zmaap_enumerate_scopes(); Guttman, E. Expires: 6 December 2001 [Page 6] Internet Draft ZMAAP API June 2001 ifa The interface on which to make the allocation. num The number of addresses requested. msec The maximum number of milliseconds to attempt allocation. Returns: NULL if no addresses can be obtained before the allotted time expires of if the parameters are bad. The lease_desc returned must be freed using zmaap_free. int zmaap_release(lease_desc ld); Parameters: ld The lease descriptor to remove from the allocation record. Returns: ZMErrCode. int zmaap_defense(lease_desc ld, int msec); Parameters: ld The lease descriptor of the multicast allocation to defend. msec The number of seconds to block while verifying the lease to defend is valid. Returns: ZMErrCode int zmaap_register(lease_desc ld, void *pv, zmaap_cb *pf, int msec); Parameters: ld The lease descriptor of the allocation app wants to be notified of if a conflict occurs. pv The opaque user parameter present in the callback function. pf The user supplied callback function. msec The maximum number of milliseconds to attempt to verify ld. Returns: ZMErrCode void zmaap_scope_name(scope_record sr, const char * tagq, char **name, char **taga); Parameters: sr The scope to get the name of. tagq The language tag desired. If NULL use default. name Will point to an allocated buffer with the scope's name. taga Will point to an allocated buffer with the name's language tag. Returns: This routine always succeeds. The strings allocated must Guttman, E. Expires: 6 December 2001 [Page 7] Internet Draft ZMAAP API June 2001 be freed with free(). void zmaap_free(void *mem); Parameters: mem Either an array of scope_records or a lease_desc allocated by the zmaap API. 5. ZMAAP API for Java The Java API uses definitions from JDK 1.4 [6]. package org.zeroconf.zmaap; import java.net.*; import java.util.*; public class ScopeRecord { public SocketAddress iaStart; // The start address of the scope range. public SocketAddress iaEnd; // The end address of the scope range. public int ttl; // The recommended TTL to use in scope. public int scopeid; // See [1], Section 4.2.2 } public BadLeaseException extends Exception { public BadLeaseException(String msg); public BadLeaseException(); } public ScopeName { public Locale locale; // The Locale of the scope name public String scopename; } public class LeaseDesc { public SocketAddress start; // The allocation's start address. public SocketAddress end; // The allocation's end address. public NetworkInterface interf; // The interface for the allocation. Guttman, E. Expires: 6 December 2001 [Page 8] Internet Draft ZMAAP API June 2001 public int id; // The allocation's lease ID. } public class ConflictListener implements EventListener { /** * This event occurs when a conflict arises with an allocation. * The ConflictListener is registered with ZMAAP.register(). * * @param alloc This is the allocation which has a conflict. * @param o This is an opaque object registered with ZMAAP. */ public void conflictEvent(LeaseDesc alloc, Object o); } public class ZMAAP { /** * @return All scopes available for allocation. */ static ScopeRecord[] availableScopes(); /** * Return the name associated with a scope, in requested language. * If the requested language is not supported, the default language * will be used. * * @param locale The locale requested for the scope name. * @param scope The scope whose name is sought. * * @return The name associated with the scope. */ static ScopeName queryScopeName(Locale locale, ScopeRecord scope); /** * Allocate a range of multicast addresses. This method will * only return after it is successful or times out. * * @param sr A ScopeRecord obtained using availableScopes(). * @param num The number of addresses requested. * @param msec Maximum number of milliseconds to attempt to * allocate the addresses. * @return An allocation. * @exception java.io.InterruptedIOException * If ZMAAP.allocate() runs out of time. * @exception java.lang.IllegalArgumentException * If the parameters are unacceptable. */ static LeaseDesc allocate(ScopeRecord sr, int num, int msec) Guttman, E. Expires: 6 December 2001 [Page 9] Internet Draft ZMAAP API June 2001 throws InterruptedIOException, IllegalArgumentException; /** * Stop defending an address allocation. This will happen * anyway if this JVM exits. * * @param ld This must represent an allocation which has either * been created with ZMAAP.allocate() or is being * defended, using ZMAAP.defend(). * @exception org.zeroconf.BadLeaseException * If the allocation in the parameter does not * correspond to a LeaseDesc this ZMAAP instance * is currently defending. */ static void release(LeaseDesc ld) throws BadLeaseException; /** * Participate in defense of an allocation. This method * will only return when successful or it times out. * * @param ld This allocation must correspond to one which * has been made by calling ZMAAP.allocate() or * which has been discovered by some other means, * such as the Session Announcement Protocol, * RFC 2974. If the allocation is unknown to the * ZMAAP object, it will attempt to validate its * existence. * * @param ms The maximum time in milliseconds to attempt to * validate the lease descriptor before giving up. * @exception java.io.InterruptedIOException * If validating the allocation runs out of time. * @exception org.zeroconf.BadLeaseException * If the allocation does not correspond to an * existing, defended address. * @exception java.lang.IllegalArgumentException If the ms argument is <= 0. */ static void defend(LeaseDesc ld, int ms) throws InterruptedIOException, BadLeaseException, IllegalArgumentException; /** * Request notification if an allocation conflict occurs. * Note that a nonexistent allocation may be passed to this * method in the LeaseDesc parameter - its validity will * not necessarily be checked - though conflicts with it * will (eventually) cause a notification to occur. * * @param cl The conflictEvent method of this object will * be called on a separate thread if a conflict Guttman, E. Expires: 6 December 2001 [Page 10] Internet Draft ZMAAP API June 2001 * is detected. * @param ld The allocation for which the ZMAAP object * must detect conflicts. * @param o An opaque user parameter which will be passed * to the ConflictListener.conflictEvent method. * @param ms The maximum time in milliseconds to attempt to * validate the lease descriptor before giving up. * @exception java.lang.IllegalArguement * If cl is null. * @exception org.zeroconf.BadLeaseException * If the allocation does not correspond to an * existing, defended address. * @exception java.io.InterruptedIOException * If validating the allocation runs out of time. */ static void register(ConflictListener cl, LeaseDesc ld, Object o, int ms) throws IllegalArgumentException, BadLeaseException, InterruptedIOException; } References [1] Catrina, O., et. al., "Zeroconf Multicast Address Allocation Protocol (ZMAAP)", draft-ietf-zeroconf-zmaap-01.txt. A work in progress. [2] Finlayson, R., "An Abstract API for Multicast Address Allocation", RFC 2771, February 2000. [3] Hanna, S., Patel, B., and M. Shah, "Multicast Address Dynamic Client Allocation Protocol (MADCAP)", RFC 2730, December 1999. [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [5] Alvestrand, H. "Tags for the Identification of Languages", RFC 3066, January 2001. [6] Java Development Kit, version 1.4.0, Beta, Documentation, http://www.javasoft.com/j2se/1.4/#documentation Acknowledgments Dave Thaler's input assisted in preparing this specification. Guttman, E. Expires: 6 December 2001 [Page 11] Internet Draft ZMAAP API June 2001 Authors' Addresses Erik Guttman Sun Microsystems Eichhoelzelstr. 7 74915 Waibstadt Germany Phone: +49 172 865 5497 Email: [email protected] Full Copyright Statement Copyright (C) The Internet Society (1999). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Guttman, E. Expires: 6 December 2001 [Page 12]