idnits 2.17.1 draft-ietf-malloc-api-01.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-03-19) 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 265 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 21 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There are 119 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 211: '... The caller MUST NOT use (i.e., join o...' RFC 2119 keyword, line 212: '...e start time. It MAY pass the address...' RFC 2119 keyword, line 215: '...ceive such announcements also MUST NOT...' 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. -------------------------------------------------------------------------------- 2 Network Working Group Ross Finlayson 3 Internet-Draft LIVE.COM 4 Expire in six months 1998.07.26 6 An Abstract API for Multicast Address Allocation 8 10 1. Status of this Memo 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, 14 and its working groups. Note that other groups may also distribute 15 working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference 20 material or to cite them other than as ``work in progress.'' 22 To learn the current status of any Internet-Draft, please check the 23 1id-abstracts.txt listing contained in the Internet-Drafts Shadow 24 Directories on ftp.is.co.za (Africa) , nic.nordu.net (Europe), 25 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast ), or 26 ftp.isi.edu (US West Coast). 28 2. Abstract 30 This document describes the ''abstract service interface'' for the dynamic 31 multicast address allocation service, as seen by applications. While it 32 does not describe a concrete API (i.e., for a specific programming 33 language), it describes - in abstract terms - the semantics of this 34 service, including the guarantees that it makes to applications. 36 Additional documents (not necessarily products of the IETF) would describe 37 concrete APIs for this service. 39 3. Introduction 41 Applications are the customers of a multicast address allocation service, 42 so a definition of this service should include not only the inter-node 43 network protocols that are used to implement it, but also the 'protocol' 44 that applications use to access the service. While APIs ("application 45 programming interfaces") for specific programming languages (or operating 46 systems) are outside the domain of the IETF, it is appropriate for us to 47 define - in abstract terms - the semantic interface that this service 48 presents to applications. Specific APIs would then be based upon this 49 abstract service interface. 51 Note that it is possible to implement the multicast address allocation 52 service in at least two different ways. The first (& perhaps most common) 53 way is for end nodes to allocate addresses by communicating with a separate 54 "Address Allocation Server" node, using the "Host to Address Allocation 55 Server" network protocol (MDHCP) [1]. Alternatively, an "Address Allocation 56 Server" implementation might be co-located (along with one or more 57 applications) on an end node, in which case some other, internal, mechanism 58 might be used to access the server. In either case, however, the abstract 59 service interface (and, presumably, any specific APIs) would remain the same. 61 The remainder of this document describes the abstract interface. 63 Note that this interface is intended only for the allocation of dynamic 64 multicast addresses, as used by the common multicast service model [2]. 65 Other multicast service models - for example, "single-source multicast" 66 (e.g., [3]) - might allocate or assign multicast addresses in other ways, 67 but this is outside the scope of this document. 69 4. Abstract Data Types 71 The interface described below uses the following abstract data types: 72 - AddressFamily: e.g., IPv4 or IPv6 73 - Scope: The "administrative scope" [4] from which a multicast address is to 74 be allocated 75 - MulticastAddress: An actual multicast address (i.e., that could subsequently 76 be used as the destination of a datagram) 77 - Duration: A (non-negative) time interval. This is used for specifying the 78 "lifetime" of a multicast address: the length of time during which an 79 allocated multicast address is guaranteed to be usable. (It is also 80 used to specify the desired start time for an "advance allocation".) 81 Note that an actual API might prefer to specify these times using 82 absolute time (e.g., in UTC) instead of relative time. 83 Relative time, however, does not require any clock synchronization. 85 5. The Abstract Interface 87 Allocating a multicast address: 88 alloc_multicast_addr(in AddressFamily family, 89 in Scope scope, 90 in Duration minDesiredLifetime, 91 in Duration maxDesiredLifetime, 92 out MulticastAddress addr, 93 out Duration lifetime) 94 This operation attempts to allocate a multicast address in a given 95 family and scope, and within a given range of desired lifetimes. 96 Unless an error occurs, it returns an allocated multicast address, 97 along with its actual lifetime (which will be within the requested 98 range). 100 The allocated multicast address is guaranteed to be usable during its 101 lifetime, even if there are topology changes during this time. 102 Also, during this time, the allocation service will make a 103 "best-efforts" attempt to not allocate this same address to others. 104 (However, once an address's lifetime has expired, it can be allocated 105 to others.) 107 Note that an application that allocates a multicast address must be 108 prepared for the possibility it will not be able to allocate a 109 *single* address for the entire lifetime it desires. For example, 110 the application may be forced to quit early, or, alternatively, to 111 occasionally 'renumber' its multicast addresses (in some application 112 or higher-level-protocol dependent way). However, because of the 113 guarantee noted above, should an application need to 'renumber', it 114 can always know this in advance, at the time it acquired its current 115 address. An application will never need to be notified 116 asynchronously of the need to 'renumber'. 118 Possible errors: 119 - bad address family 120 - bad scope 121 - bad lifetime durations (e.g., max < min) 122 - no address can be allocated 124 Querying the lifetime of a multicast address: 125 query_multicast_addr_lifetime(in AddressFamily family, 126 in MulticastAddress addr, 127 out Duration lifetime) 128 This operation attempts to query the lifetime of a previously 129 allocated multicast address. 131 Possible errors: 132 - bad address family 133 - the address was not one that we[*] had allocated 134 (or it has already expired) 136 Changing a multicast address's lifetime: 137 change_multicast_addr_lifetime(in AddressFamily family, 138 in MulticastAddress addr, 139 in Duration minDesiredLifetime, 140 in Duration maxDesiredLifetime, 141 out Duration lifetime) 142 This operation attempts to change the lifetime of a previously 143 allocated multicast address. Unless an error occurs, it returns 144 the new lifetime (which might remain unchanged). 146 Possible errors: 147 - bad address family 148 - bad durations (e.g., max < min) 149 - the address was not one that we[*] had allocated 150 (or it has already expired) 152 Deallocating a multicast address: 153 deallocate_multicast_addr(in AddressFamily family, 154 in MulticastAddress addr) 155 This operation attempts to deallocate a previously allocated 156 multicast address. 158 Possible errors: 159 - bad address family 160 - the address was not one that we[*] had allocated 161 (or it has already expired) 163 Querying the set of usable multicast address 'scopes': 164 get_multicast_addr_scopes(in AddressFamily family, 165 out "set of" Scope) 166 This operation returns the set of administrative multicast address 167 scopes that are defined for this node. 169 Possible errors: 170 - bad address family 172 [*] An open question is: Who is allowed to deallocate (or query or change the 173 lifetime of) a previously allocated multicast address? Because these 174 operations have security implications, we guarantee only that: 175 A previously allocated multicast address can be deallocated (or have 176 its lifetime queried or changed) by the same "principal", and on the 177 same node, as that which originally allocated it. 178 The definition of "principal", however, is implementation dependent. 179 (It might, for example, be a "user" in the host operating system.) 181 Advance allocation 182 ================== 183 With the basic address allocation operation - "alloc_multicast_addr" - 184 described earlier, a multicast address - once allocated - can be used 185 immediately (and until its lifetime expires). During this time, the 186 address is not available for allocation to others. 188 It is also possible to allocate a multicast address *in advance* - i.e., 189 so that it has a future "start time" as well as an expiration time. 190 Before the start time, the multicast address may be allocated to others. 192 Advance allocation is convenient for allocating addresses for events that 193 begin far in the future - e.g., several weeks or months away. Without 194 advance allocation, it would be necessary to reserve an address for a long 195 period of time - even when it will not be used. Such a request would not 196 only be a wasteful use of the multicast address space, but it may also be 197 difficult to implement (especially since address allocations are expected 198 to remain valid in spite of topology changes). 200 advance_alloc_multicast_addr(in AddressFamily family, 201 in Scope scope, 202 in Duration minDesiredStartTime, 203 in Duration maxDesiredStartTime, 204 in Duration minDesiredLifetime, 205 in Duration maxDesiredLifetime, 206 out MulticastAddress addr, 207 out Duration startTime, 208 out Duration lifetime) 209 This operation is like "alloc_multicast_addr", except that it 210 returns a start time along with a multicast address (and lifetime). 211 The caller MUST NOT use (i.e., join or send packets to) this 212 multicast address prior to the start time. It MAY pass the address 213 to others (e.g., in session directory (SDP) announcements [5]), 214 provided that also passes the start time. Parties (such as session 215 directory browsers) that receive such announcements also MUST NOT 216 use the multicast address prior to the start time. 218 Possible errors: the same as "alloc_multicast_addr", plus: 219 - bad start time durations (e.g., max < min) 220 - requested start times conflict with requested lifetimes 221 (i.e., min start time > max lifetime) 223 query_multicast_addr_start_time(in AddressFamily family, 224 in MulticastAddress addr, 225 out Duration startTime) 226 This operation attempts to query the start time of a previously 227 allocated multicast address. 229 Possible errors: the same as "query_multicast_addr_lifetime" 231 change_multicast_addr_start_time(in AddressFamily family, 232 in MulticastAddress addr, 233 in Duration minDesiredStartTime, 234 in Duration maxDesiredStartTime, 235 out Duration startTime) 236 This operation attempts to change the start time of a previously 237 allocated multicast address. Unless an error occurs, it returns 238 the new start time (which might remain unchanged). 240 Possible errors: the same as "change_multicast_addr_lifetime" 242 6. References 244 [1] The "Host to Address Allocation Server" Protocol (MDHCP) 245 Work-in-Progress, IETF MALLOC Working Group 246 [2] Deering, S., "Host Extensions for IP Multicasting", RFC 1112, 247 August 1989. 248 [3] Cheriton, D., Holbrook, H., "EXPRESS Multicast", 249 Work-in-Progress, Stanford University. 250 [4] Meyer, D., 251 "Administratively Scoped IP Multicast", 252 Work-in-Progress, 253 Internet-Draft "draft-ietf-mboned-admin-ip-space-06.txt", June, 1998. 254 [5] Handley, M., Jacobson, V. SDP: Session Description Protocol 255 Work-in-Progress, 256 Internet-Draft "draft-ietf-mmusic-sdp-07.txt", April, 1998. 258 7. Author's Address 260 Ross Finlayson, 261 Live Networks, Inc. (LIVE.COM) 262 email: finlayson@live.com 263 WWW: http://www.live.com/