idnits 2.17.1 draft-ietf-malloc-api-03.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-20) 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 300 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 66 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** 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 238: '... The caller MUST NOT use (i.e., j...' RFC 2119 keyword, line 241: '... It MAY pass these addresses to...' RFC 2119 keyword, line 244: '...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: 12 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.07 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 A "best-effort" attempt will be made to maintain multicast routing 109 for allocated multicast addresses during their lifetime, even if 110 there are topology changes (such as a change of upstream provider) 111 during this time. Also, during this time, the allocation service will 112 make a "best-effort" attempt to not allocate any of these addresses 113 to others. (However, once an address's lifetime has expired, it can 114 be allocated to others.) 116 Note that multicast addresses are allocated for a limited lifetime. 117 An application may attempt to extend this lifetime, but this 118 operation may fail. Therefore, an application must be prepared 119 for the possibility it will not be able to use the same addresses 120 for as long as it desires. In particular, the application must 121 be prepared to either quit early (because its original multicast 122 address assignments have expired), or, alternatively, to occasionally 123 'renumber' its multicast addresses (in some application or 124 higher-level-protocol dependent way), by making a new allocation. 125 However, because of the guarantee noted above, if an application needs 126 to 'renumber', it will always know this in advance, at the time it 127 acquired its current address(es). An application will never need 128 to be notified asynchronously of the need to 'renumber'. 130 Possible errors: 131 - bad address family 132 - bad scope 133 - bad desired number of addresses (e.g., max < min) 134 - bad desired lifetime durations (e.g., max < min) 135 - no addresses can be allocated (for the requested parameters) 137 Note that a concrete (i.e., programming language-specific) API for 138 multicast address allocation will probably include additional, 139 specialized variants of this general allocation operation. For 140 instance, it may include operations for allocating only a single 141 address (i.e., minDesiredAddresses = maxDesiredAddresses = 1), 142 and/or for (attempting to) allocate an address with a single, 143 fixed lifetime (i.e., minDesiredLifetime = minDesiredLifetime). 145 Querying the lifetime of a multicast address: 146 query_multicast_addr_lifetime(in AddressFamily family, 147 in MulticastAddress addr, 148 out Duration lifetime) 149 This operation attempts to query the lifetime of a previously 150 allocated multicast address. 152 Possible errors: 153 - bad address family 154 - the address was not one that we[*] had allocated 155 (or they have already expired) 157 Changing multicast addresses' lifetime: 158 change_multicast_addr_lifetime(in AddressFamily family, 159 in MulticastAddressRange addresses, 160 in Duration minDesiredLifetime, 161 in Duration maxDesiredLifetime, 162 out Duration lifetime) 163 This operation attempts to change the lifetime of previously 164 allocated multicast addresses. Unless an error occurs, it returns 165 the new lifetime (which might remain unchanged). 167 Possible errors: 168 - bad address family 169 - bad durations (e.g., max < min) 170 - the addresses' lifetime could not be changed 171 (and the existing lifetime was not in the requested range 172 [minDesiredLifetime,maxDesiredLifetime]) 173 - the addresses were not ones that we[*] had allocated 174 (or they have already expired) 176 Deallocating multicast addresses: 177 deallocate_multicast_addr(in AddressFamily family, 178 in MulticastAddressRange addresses) 179 This operation attempts to deallocate previously allocated 180 multicast addresses. 182 Possible errors: 183 - bad address family 184 - the addresses were not ones that we[*] had allocated 185 (or they have already expired) 187 Querying the set of usable multicast address 'scopes': 188 get_multicast_addr_scopes(in AddressFamily family, 189 out "set of" Scope) 190 This operation returns the set of administrative multicast address 191 scopes that are defined for this node. 193 Possible errors: 194 - bad address family 196 [*] An open question is: Who is allowed to deallocate (or query or change the 197 lifetime of) a previously allocated multicast address? This is an 198 implementation-specific decision, dependent upon the security policy of the 199 host system, and is not specified in this abstract API. One possible 200 starting point, however, is the following: 201 A previously allocated multicast address can be deallocated (or have 202 its lifetime queried or changed) by the same "principal", and on the 203 same node, as that which originally allocated it. ("principal" might, 204 for example, be a "user" in the host operating system.) 206 Advance allocation 207 ================== 208 With the basic address allocation operation - "alloc_multicast_addr" - 209 described earlier, a multicast address - once allocated - can be used 210 immediately (and until its lifetime expires). During this time, the 211 address is not available for allocation to others. 213 It is also possible to allocate a multicast address *in advance* - i.e., 214 so that it has a future "start time" as well as an expiration time. 215 Before the start time, the multicast address may be allocated to others. 217 Advance allocation is convenient for allocating addresses for events that 218 begin far in the future - e.g., several weeks or months away. Without 219 advance allocation, it would be necessary to reserve an address for a long 220 period of time - even when it will not be used. Such a request would not 221 only be a wasteful use of the multicast address space, but it may also be 222 difficult to implement (especially since address allocations are expected 223 to remain valid in spite of topology changes). 225 advance_alloc_multicast_addr(in AddressFamily family, 226 in Scope scope, 227 in Integer minDesiredAddresses, 228 in Integer maxDesiredAddresses, 229 in Duration minDesiredStartTime, 230 in Duration maxDesiredStartTime, 231 in Duration minDesiredLifetime, 232 in Duration maxDesiredLifetime, 233 out MulticastAddressRange addresses, 234 out Duration startTime, 235 out Duration lifetime) 236 This operation is like "alloc_multicast_addr", except that it returns 237 a start time along with a multicast address range (and lifetime). 238 The caller MUST NOT use (i.e., join or send packets to) any of these 239 multicast addresses prior to the start time (unless, of course, an 240 address happens to be used as part of a different multicast session). 241 It MAY pass these addresses to others (e.g., in session directory 242 (SDP) announcements [5]), provided that also passes the start time. 243 Parties (such as session directory browsers) that receive such 244 announcements also MUST NOT use the multicast address prior to the 245 start time. 247 Possible errors: the same as "alloc_multicast_addr", plus: 248 - bad start time durations (e.g., max < min) 249 - requested start times conflict with requested lifetimes 250 (i.e., min start time > max lifetime) 252 query_multicast_addr_start_time(in AddressFamily family, 253 in MulticastAddress addr, 254 out Duration startTime) 255 This operation attempts to query the start time of a previously 256 allocated multicast address. 258 Possible errors: the same as "query_multicast_addr_lifetime" 260 change_multicast_addr_start_time(in AddressFamily family, 261 in MulticastAddressRange addresses, 262 in Duration minDesiredStartTime, 263 in Duration maxDesiredStartTime, 264 out Duration startTime) 265 This operation attempts to change the start time of previously 266 allocated multicast addresses. Unless an error occurs, it returns 267 the new start time (which might remain unchanged). 269 Possible errors: the same as "change_multicast_addr_lifetime" 271 Note that a concrete implementation of this API does not have to provide 272 separate operations (as described above) for advance allocation. As an 273 alternative, each of the "lifetime" parameters in the earlier operations 274 could be specified as a pair of durations: (start,end). 276 6. References 278 [1] The "Host to Address Allocation Server" Protocol (MDHCP) 279 Work-in-Progress, IETF MALLOC Working Group 280 [2] Deering, S., "Host Extensions for IP Multicasting", RFC 1112, 281 August 1989. 282 [3] Cheriton, D., Holbrook, H., "EXPRESS Multicast", 283 Work-in-Progress, Stanford University. 284 [4] Meyer, D., 285 "Administratively Scoped IP Multicast", 286 Work-in-Progress, 287 Internet-Draft "draft-ietf-mboned-admin-ip-space-06.txt", June, 1998. 288 [5] Handley, M., Jacobson, V. SDP: Session Description Protocol 289 Work-in-Progress, 290 Internet-Draft "draft-ietf-mmusic-sdp-07.txt", April, 1998. 292 7. Author's Address 294 Ross Finlayson, 295 Live Networks, Inc. (LIVE.COM) 296 email: finlayson@live.com 297 WWW: http://www.live.com/