idnits 2.17.1 draft-ietf-malloc-api-02.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-27) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 287 lines 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 61 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There are 2 instances of lines with control characters in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 231: '... The caller MUST NOT use (i.e., j...' RFC 2119 keyword, line 234: '... It MAY pass these addresses to...' RFC 2119 keyword, line 237: '...nouncements also MUST NOT use the mult...' Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. 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' -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '5' Summary: 13 errors (**), 0 flaws (~~), 2 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Ross Finlayson 2 Internet-Draft LIVE.COM 3 Expire in six months 1998.08.04 5 An Abstract API for Multicast Address Allocation 7 9 1. Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference 19 material or to cite them other than as ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check the 22 1id-abstracts.txt listing contained in the Internet-Drafts Shadow 23 Directories on ftp.is.co.za (Africa) , nic.nordu.net (Europe), 24 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast ), or 25 ftp.isi.edu (US West Coast). 27 2. Abstract 29 This document describes the ''abstract service interface'' for the dynamic 30 multicast address allocation service, as seen by applications. While it 31 does not describe a concrete API (i.e., for a specific programming 32 language), it describes - in abstract terms - the semantics of this 33 service, including the guarantees that it makes to applications. 35 Additional documents (not necessarily products of the IETF) would describe 36 concrete APIs for this service. 38 3. Introduction 40 Applications are the customers of a multicast address allocation service, 41 so a definition of this service should include not only the inter-node 42 network protocols that are used to implement it, but also the 'protocol' 43 that applications use to access the service. While APIs ("application 44 programming interfaces") for specific programming languages (or operating 45 systems) are outside the domain of the IETF, it is appropriate for us to 46 define - in abstract terms - the semantic interface that this service 47 presents to applications. Specific APIs would then be based upon this 48 abstract service interface. 50 Note that it is possible to implement the multicast address allocation 51 service in at least two different ways. The first (& perhaps most common) 52 way is for end nodes to allocate addresses by communicating with a separate 53 "Address Allocation Server" node, using the "Host to Address Allocation 54 Server" network protocol (MDHCP) [1]. Alternatively, an "Address Allocation 55 Server" implementation might be co-located (along with one or more 56 applications) on an end node, in which case some other, internal, mechanism 57 might be used to access the server. In either case, however, the abstract 58 service interface (and, presumably, any specific APIs) would remain the same. 60 The remainder of this document describes the abstract interface. 62 Note that this interface is intended only for the allocation of dynamic 63 multicast addresses, as used by the common multicast service model [2]. 64 Other multicast service models - for example, "single-source multicast" 65 (e.g., [3]) - might allocate or assign multicast addresses in other ways, 66 but this is outside the scope of this document. 68 4. Abstract Data Types 70 The interface described below uses the following abstract data types: 71 - AddressFamily: e.g., IPv4 or IPv6 72 - Scope: The "administrative scope" [4] from which a multicast address is 73 to be allocated. (In practice, an implementation of this abstract 74 data type might specify not only a multicast address range, but also 75 a textual description (e.g., "local"), and possibly a default TTL 76 for this scope.) 77 - MulticastAddress: An actual multicast address (i.e., that could subsequently 78 be used as the destination of a datagram) 79 - MulticastAddressRange: A set of contiguous "MulticastAddress"es 80 - Duration: A (non-negative) time interval. This is used for specifying the 81 "lifetime" of a multicast address: the length of time during which an 82 allocated multicast address is guaranteed to be usable. (It is also 83 used to specify the desired start time for an "advance allocation".) 84 Note that an actual API might prefer to specify these times using 85 absolute time (e.g., in UTC) instead of relative time. 86 Relative time, however, does not require any clock synchronization. 88 5. The Abstract Interface 90 Allocating a multicast address: 91 alloc_multicast_addr(in AddressFamily family, 92 in Scope scope, 93 in Integer minDesiredAddresses, 94 in Integer maxDesiredAddresses, 95 in Duration minDesiredLifetime, 96 in Duration maxDesiredLifetime, 97 out MulticastAddressRange addresses, 98 out Duration lifetime) 99 This operation attempts to allocate a contiguous set of 100 multicast addresses (the size of this set is in the range 101 [minDesiredAddresses, maxDesiredAddresses]) within the given 102 family and scope, and within a given range of desired lifetimes. 103 Unless an error occurs, it returns a range of allocated 104 multicast addresses, along with their actual lifetime 105 (which will be within the requested range). (Each address within 106 the returned range will have this same lifetime.) 108 The allocated multicast addresses are guaranteed to be usable during 109 their lifetime, even if there are topology changes during this time. 110 Also, during this time, the allocation service will make a 111 "best-efforts" attempt to not allocate any of these addresses to 112 others. (However, once an address's lifetime has expired, it can be 113 allocated to others.) 115 Note that an application that allocates multicast addresses must be 116 prepared for the possibility it will not be able to use the same 117 addresses for as long as it desires. Because of this, the application 118 must be prepared to either quit early (because its original multicast 119 address assignments have expired), or, alternatively, to occasionally 120 'renumber' its multicast addresses (in some application or 121 higher-level-protocol dependent way), by making a new allocation. 122 However, because of the guarantee noted above, if an application needs 123 to 'renumber', it will always know this in advance, at the time it 124 acquired its current address(es). An application will never need 125 to be notified asynchronously of the need to 'renumber'. 127 Possible errors: 128 - bad address family 129 - bad scope 130 - bad desired number of addresses (e.g., max < min) 131 - bad desired lifetime durations (e.g., max < min) 132 - no addresses can be allocated (for the requested parameters) 134 Note that a concrete (i.e., programming language-specific) API for 135 multicast address allocation will probably include additional, 136 specialized variants of this general allocation operation. For 137 instance, it may include operations for allocating only a single 138 address (i.e., minDesiredAddresses = maxDesiredAddresses = 1), 139 and/or for (attempting to) allocate an address with a single, 140 fixed lifetime (i.e., minDesiredLifetime = minDesiredLifetime). 142 Querying the lifetime of a multicast address: 143 query_multicast_addr_lifetime(in AddressFamily family, 144 in MulticastAddress addr, 145 out Duration lifetime) 146 This operation attempts to query the lifetime of a previously 147 allocated multicast address. 149 Possible errors: 150 - bad address family 151 - the address was not one that we[*] had allocated 152 (or they have already expired) 154 Changing multicast addresses' lifetime: 155 change_multicast_addr_lifetime(in AddressFamily family, 156 in MulticastAddressRange addresses, 157 in Duration minDesiredLifetime, 158 in Duration maxDesiredLifetime, 159 out Duration lifetime) 160 This operation attempts to change the lifetime of previously 161 allocated multicast addresses. Unless an error occurs, it returns 162 the new lifetime (which might remain unchanged). 164 Possible errors: 165 - bad address family 166 - bad durations (e.g., max < min) 167 - the addresses were not ones that we[*] had allocated 168 (or they have already expired) 170 Deallocating multicast addresses: 171 deallocate_multicast_addr(in AddressFamily family, 172 in MulticastAddressRange addresses) 173 This operation attempts to deallocate previously allocated 174 multicast addresses. 176 Possible errors: 177 - bad address family 178 - the addresses were not ones that we[*] had allocated 179 (or they have already expired) 181 Querying the set of usable multicast address 'scopes': 182 get_multicast_addr_scopes(in AddressFamily family, 183 out "set of" Scope) 184 This operation returns the set of administrative multicast address 185 scopes that are defined for this node. 187 Possible errors: 188 - bad address family 190 [*] An open question is: Who is allowed to deallocate (or query or change the 191 lifetime of) a previously allocated multicast address? Because these 192 operations have security implications, we guarantee only that: 193 A previously allocated multicast address can be deallocated (or have 194 its lifetime queried or changed) by the same "principal", and on the 195 same node, as that which originally allocated it. 196 The definition of "principal", however, is implementation dependent. 197 (It might, for example, be a "user" in the host operating system.) 199 Advance allocation 200 ================== 201 With the basic address allocation operation - "alloc_multicast_addr" - 202 described earlier, a multicast address - once allocated - can be used 203 immediately (and until its lifetime expires). During this time, the 204 address is not available for allocation to others. 206 It is also possible to allocate a multicast address *in advance* - i.e., 207 so that it has a future "start time" as well as an expiration time. 208 Before the start time, the multicast address may be allocated to others. 210 Advance allocation is convenient for allocating addresses for events that 211 begin far in the future - e.g., several weeks or months away. Without 212 advance allocation, it would be necessary to reserve an address for a long 213 period of time - even when it will not be used. Such a request would not 214 only be a wasteful use of the multicast address space, but it may also be 215 difficult to implement (especially since address allocations are expected 216 to remain valid in spite of topology changes). 218 advance_alloc_multicast_addr(in AddressFamily family, 219 in Scope scope, 220 in Integer minDesiredAddresses, 221 in Integer maxDesiredAddresses, 222 in Duration minDesiredStartTime, 223 in Duration maxDesiredStartTime, 224 in Duration minDesiredLifetime, 225 in Duration maxDesiredLifetime, 226 out MulticastAddressRange addresses, 227 out Duration startTime, 228 out Duration lifetime) 229 This operation is like "alloc_multicast_addr", except that it returns 230 a start time along with a multicast address range (and lifetime). 231 The caller MUST NOT use (i.e., join or send packets to) any of these 232 multicast addresses prior to the start time (unless, of course, an 233 address happens to be used as part of a different multicast session). 234 It MAY pass these addresses to others (e.g., in session directory 235 (SDP) announcements [5]), provided that also passes the start time. 236 Parties (such as session directory browsers) that receive such 237 announcements also MUST NOT use the multicast address prior to the 238 start time. 240 Possible errors: the same as "alloc_multicast_addr", plus: 241 - bad start time durations (e.g., max < min) 242 - requested start times conflict with requested lifetimes 243 (i.e., min start time > max lifetime) 245 query_multicast_addr_start_time(in AddressFamily family, 246 in MulticastAddress addr, 247 out Duration startTime) 248 This operation attempts to query the start time of a previously 249 allocated multicast address. 251 Possible errors: the same as "query_multicast_addr_lifetime" 253 change_multicast_addr_start_time(in AddressFamily family, 254 in MulticastAddressRange addresses, 255 in Duration minDesiredStartTime, 256 in Duration maxDesiredStartTime, 257 out Duration startTime) 258 This operation attempts to change the start time of previously 259 allocated multicast addresses. Unless an error occurs, it returns 260 the new start time (which might remain unchanged). 262 Possible errors: the same as "change_multicast_addr_lifetime" 264 6. References 266 [1] The "Host to Address Allocation Server" Protocol (MDHCP) 267 Work-in-Progress, IETF MALLOC Working Group 268 [2] Deering, S., "Host Extensions for IP Multicasting", RFC 1112, 269 August 1989. 270 [3] Cheriton, D., Holbrook, H., "EXPRESS Multicast", 271 Work-in-Progress, Stanford University. 272 [4] Meyer, D., 273 "Administratively Scoped IP Multicast", 274 Work-in-Progress, 275 Internet-Draft "draft-ietf-mboned-admin-ip-space-06.txt", June, 1998. 276 [5] Handley, M., Jacobson, V. SDP: Session Description Protocol 277 Work-in-Progress, 278 Internet-Draft "draft-ietf-mmusic-sdp-07.txt", April, 1998. 280 7. Author's Address 282 Ross Finlayson, 283 Live Networks, Inc. (LIVE.COM) 284 email: finlayson@live.com 285 WWW: http://www.live.com/