idnits 2.17.1 draft-ietf-malloc-api-06.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): ---------------------------------------------------------------------------- ** 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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == 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 388 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 55 instances of too long lines in the document, the longest one being 4 characters in excess of 72. 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) -- Looks like a reference, but probably isn't: 'MulticastAddressSet' on line 104 -- Looks like a reference, but probably isn't: 'AddressFamily' on line 105 -- Looks like a reference, but probably isn't: 'Time' on line 107 == Unused Reference: '5' is defined on line 372, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 1766 (ref. '4') (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2327 (ref. '5') (Obsoleted by RFC 4566) -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 8 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 1999.06.25 5 An Abstract API for Multicast Address Allocation 7 9 1. Status of this Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet- 22 Drafts as reference material or to cite them other than as 23 "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 2. Abstract 33 This document describes the ''abstract service interface'' for the dynamic 34 multicast address allocation service, as seen by applications. While it 35 does not describe a concrete API (i.e., for a specific programming 36 language), it describes - in abstract terms - the semantics of this 37 service, including the guarantees that it makes to applications. 39 Additional documents (not necessarily products of the IETF) would describe 40 concrete APIs for this service. 42 3. Introduction 44 Applications are the customers of a multicast address allocation service, 45 so a definition of this service should include not only the inter-node 46 network protocols that are used to implement it, but also the 'protocol' 47 that applications use to access the service. While APIs ("application 48 programming interfaces") for specific programming languages (or operating 49 systems) are outside the domain of the IETF, it is appropriate for us to 50 define - in abstract terms - the semantic interface that this service 51 presents to applications. Specific APIs would then be based upon this 52 abstract service interface. 54 Note that it is possible to implement the multicast address allocation 55 service in at least two different ways. The first (& perhaps most common) 56 way is for end nodes to allocate addresses by communicating with a separate 57 "Address Allocation Server" node, using the "Host to Address Allocation 58 Server" network protocol (MADCAP) [1][7]. Alternatively, an 59 "Address Allocation Server" implementation might be co-located (along 60 with one or more applications) on an end node, in which case some other, 61 internal, mechanism might be used to access the server. In either case, 62 however, the abstract service interface (and, presumably, any specific 63 APIs) would remain the same. 65 The remainder of this document describes the abstract interface. 67 Note that this interface is intended only for the allocation of dynamic 68 multicast addresses, as used by the normal multicast service model [2]. 69 Future multicast service models might allocate or assign multicast 70 addresses in other ways, but this is outside the scope of this document. 72 4. Abstract Data Types 74 The interface described below uses the following abstract data types: 75 - AddressFamily: e.g., IPv4 or IPv6 76 - MulticastAddress: An actual multicast address (i.e., that could 77 subsequently 78 be used as the destination of a datagram) 79 - MulticastAddressSet: A set of "MulticastAddress"es 80 - LanguageTag: The code for a (human) language, as defined in [4] 81 - Scope: An "administrative scope" [3] from which a multicast address is 82 to be allocated. Each scope is a "MulticastAddressSet", 83 with an associated set of (character-string) names - indexed by 84 "LanguageTag". (Each language tag has at most one corresponding 85 name, 86 per scope.) For each scope, a (language tag, name) pair may be 87 defined to be the 'default' name for this scope. (See the section 88 "Querying the name of a scope" below.) 89 (An implementation of this abstract data type might also include 90 other 91 information, such as a default TTL for the scope.) 92 - Time: An (absolute) event time. This is used for specifying the 93 "lifetime" of a multicast address: the period of time during which 94 an 95 allocated multicast address is guaranteed to be availabile. (It is 96 also used to specify the desired start time for an 97 "advance allocation".) 98 Note that a concrete API might prefer to specify some of these 99 times as relative times (i.e., relative to the current time-of-day), 100 rather than absolute time. (Relative times have the advantage of 101 not requiring clock synchronization.) 102 - Lease: A compound data type that describes the result of a (successful) 103 multicast address allocation. It consists of: 104 - [MulticastAddressSet] The set of addresses that were allocated; 105 - [AddressFamily] The address family of these addresses 106 - [Time] The lifetime of these addresses (the same for each address) 107 - [Time] The "start time" of the allocation. (See the discussion of 108 "advance allocation" below.) 109 (A concrete API would likely also include a 110 MADCAP "Client Identifier" [1].) 111 - NestingRelationship: A binary data type that describes whether 112 or not two scopes nest. Two scopes nest if traffic sent 113 sent to a multicast group within one scope could be seen 114 by all hosts present within the other scope were they to 115 join the multicast group within the first scope. This value 116 would be "False" for overlapping scopes where only some 117 (or none) of the hosts within the second scope could see 118 traffic sent to an address due to the presence of an 119 administratively scoped boundary. In cases where the first 120 and second scopes are topologically identical this value 121 would be "True." 122 - Status: A result code. 124 5. The Abstract Interface 126 Allocating a multicast address: 127 alloc_multicast_addr(in AddressFamily family, 128 in Scope scope, 129 in Integer minDesiredAddresses, 130 in Integer maxDesiredAddresses, 131 in Time minDesiredStartTime, 132 in Time maxDesiredStartTime, 133 in Time minDesiredLifetime, 134 in Time maxDesiredLifetime, 135 out Lease multicastAddressSetLease, 136 out Status status) 137 This operation attempts to allocate a set of multicast addresses 138 (the size of this set is in the range 139 [minDesiredAddresses, maxDesiredAddresses]) within the given address 140 family and scope, and within a given range of desired 141 lifetimes. ("minDesiredStartTime" and "maxDesiredStartTime" are 142 used to specify "advance allocation"; this is described in more 143 detail below.) 145 If the address allocation succeeds, the result is returned in 146 "multicastAddressSetLease" (with "status" = OK). 148 A "best-effort" attempt will be made to maintain multicast routing 149 for the allocated multicast addresses during their lifetime, even if 150 there are topology changes (such as a change of upstream provider) 151 during this time. Also, during this time, the allocation service 152 will 153 make a "best-effort" attempt to not allocate any of these addresses 154 to others. (However, once an address's lifetime has expired, it can 155 be allocated to others.) 157 Note that multicast addresses are allocated for a limited lifetime. 158 An application may attempt to extend this lifetime, but this 159 operation may fail. Therefore, an application must be prepared 160 for the possibility it will not be able to use the same addresses 161 for as long as it desires. In particular, the application must 162 be prepared to either quit early (because its original multicast 163 address assignments have expired), or, alternatively, to 164 occasionally 165 'renumber' its multicast addresses (in some application or 166 higher-level-protocol dependent way), by making a new allocation. 167 However, because of the guarantee noted above, if an application 168 needs 169 to 'renumber', it will always know this in advance, at the time it 170 acquired its current address(es). An application will never need 171 to be notified asynchronously of the need to 'renumber'. 173 Possible errors: 174 - bad address family 175 - bad scope 176 - bad desired number of addresses (e.g., max < min) 177 - bad desired lifetimes (e.g., max < min) 178 - errors with the two "start time" parameters (see 179 "Advance allocation" below) 180 - no addresses can be allocated (for the requested 181 parameters) 183 An allocation attempt can also fail with a result "status" code 184 of TRY_LATER, indicating that the requested allocation cannot 185 be made at this time, but that it might succeed if the caller 186 retries the attempt at some future time. (This future time is 187 returned in the "start time" field of the 188 "multicastAddressSetLease"; 189 the other parts of this lease are undefined.) 191 Note that a concrete (i.e., programming language-specific) API for 192 multicast address allocation will probably include additional, 193 specialized variants of this general allocation operation. For 194 instance, it may include separate operations for: 195 - allocating only a single address 196 (i.e., minDesiredAddresses = maxDesiredAddresses = 1); 197 - (attempting to) allocate an address with a single, fixed 198 lifetime (i.e., minDesiredLifetime = maxDesiredLifetime); 199 - (attempting to) allocate an address for immediate use 200 (i.e., minDesiredStartTime = maxDesiredStartTime = 'now') 202 Changing multicast addresses' lifetime: 203 change_multicast_addr_lifetime(in Lease multicastAddressSetLease, 204 in Time minDesiredLifetime, 205 in Time maxDesiredLifetime, 206 out Time lifetime) 207 This operation attempts to change the lifetime of previously 208 allocated multicast addresses. Unless an error occurs, it returns 209 the new lifetime (which might remain unchanged). 211 Possible errors: 212 - bad address family 213 - bad durations (e.g., max < min) 214 - the addresses' lifetime could not be changed 215 (and the existing lifetime was not in the requested range 216 [minDesiredLifetime,maxDesiredLifetime]) 217 - the addresses were not ones that we[*] had allocated 218 (or they have already expired) 220 Deallocating multicast addresses: 221 deallocate_multicast_addr(in Lease multicastAddressSetLease) 222 This operation attempts to deallocate previously allocated 223 multicast addresses. 225 Possible errors: 226 - bad address family 227 - the addresses were not ones that we[*] had allocated 228 (or they have already expired) 230 Querying the set of usable multicast address scopes: 231 get_multicast_addr_scopes(in AddressFamily family, 232 out "set of" Scope) 233 This operation returns the set of administrative multicast address 234 scopes that are defined for this node. 236 Possible errors: 237 - bad address family 239 Querying the name of a scope: 240 get_scope_name(in Scope scope, 241 in LanguageTag language, 242 out String name, 243 out LanguageTag languageForName) 244 This operation returns a character-string name for a given scope. 245 If the scope has a name in the specified "language", then this name 246 (and language) is returned. Otherwise, the scope's default 247 (language, name) pair is returned. 249 Possible errors: 250 - bad scope 252 Querying the nesting state of known usable multicast address scopes: 253 get_scope_nesting_state(in "set of" Scope, 254 out "array of" NestingRelationship) 256 Possible errors: 257 - bad scope. 258 - nesting state undetermined at this time. 260 This operation would return an array that shows the 261 current nesting relationships between the supplied 262 set of scopes which would have previously been supplied 263 via the get_multicast_addr_scopes(...) function. 265 Querying the set of scopes that a given scope is known to nest inside: 266 get_larger_scopes(in Scope, 267 out "set of" Scope) 269 This operation returns the set of administrative multicast 270 address scopes that are known to encompass the supplied 271 Scope. 273 Possible errors: 274 - bad scope. 275 - nesting state undetermined at this time. 277 Querying the set of scopes that are known to nest inside a given scope: 278 get_smaller_scopes(in Scope, 279 out "set of" Scope) 281 This operation returns the set of administrative multicast 282 address scopes that are known to nest inside the supplied 283 Scope (NB this would include those scopes that are 284 topologically identical to the supplied scope). 286 Possible errors: 287 - bad scope. 288 - nesting state undetermined at this time. 290 [*] The decision as to who is allowed to deallocate (or change the lifetime 291 of) a previously allocated multicast address set lease is 292 implementation-specific, and depends upon the security policy of the host 293 system. Thus it is not specified in this abstract API. One possible 294 starting point, however, is the following: 295 A previously allocated multicast address can be deallocated (or have 296 its lifetime queried or changed) by the same "principal", and on the 297 same node, as that which originally allocated it. ("principal" 298 might, 299 for example, be a "user" in the host operating system.) 301 Advance allocation 302 ================== 303 By specifying "minDesiredStartTime = maxDesiredStartTime = 'now'", 304 the address allocation operation - "alloc_multicast_addr" - described above 305 can be used to request a set of multicast addresses that can be used 306 *immediately* (and until their lifetime expires). During this whole time, 307 the addresses are not available for allocation to others. 309 It is also possible - using the "minDesiredStartTime" and 310 "maxDesiredStartTime" parameters - to allocate multicast addresses 311 *in advance* - i.e., so that they have a future "start time" as well as 312 an expiration time. Before the start time, the multicast addresses may 313 be allocated to others. 315 Advance allocation is convenient for allocating addresses for events that 316 begin far in the future - e.g., several weeks or months away. Without 317 advance allocation, it would be necessary to reserve an address for a long 318 period of time - even when it will not be used. Such a request would not 319 only be a wasteful use of the multicast address space, but it may also be 320 difficult to implement (especially since address allocations are expected 321 to remain valid in spite of topology changes). 323 Advance allocation requests can produce the following errors (in addition to 324 those defined earlier): 325 - bad start time durations (e.g., max < min) 326 - requested start times conflict with requested lifetimes 327 (i.e., min start time > max lifetime) 329 The following operation is also defined: 331 change_multicast_addr_start_time(in Lease multicastAddressSetLease, 332 in Time minDesiredStartTime, 333 in Time maxDesiredStartTime, 334 out Time startTime) 335 This operation attempts to change the start time of previously 336 allocated multicast addresses. Unless an error occurs, it returns 337 the new start time (which might remain unchanged). 339 Possible errors: the same as "change_multicast_addr_lifetime" 341 6. Security Considerations 343 As noted in point [*] above, each implementation of this abstract API should 344 define a security policy that specifies when (and by whom) a previously 345 allocated multicast address can be deallocated (or queried, or have its 346 lifetime changed). 348 Because multicast addresses are a finite resource, there is a potential for 349 a "denial of service" attack by allocating a large number of multicast 350 addresses without deallocating them. Preventing such an attack, however, 351 is not the role of the API, but rather by the underlying MAAS ("Multicast 352 Address Allocation Server(s)" [6]). 354 7. Acknowledgements 356 Many thanks to other participants in the "MALLOC" working group 357 - in particular Steve Hanna, Dave Thaler , and Roger Kermode - for their 358 valuable comments. 360 8. References 362 [1] Patel, B., Shah, M., Hanna, S., 363 "Multicast Address Dynamic Client Allocation Protocol (MADCAP)", 364 Work-in-Progress, Internet-Draft "draft-ietf-malloc-madcap-05.txt", 365 May, 1999. 366 [2] Deering, S., "Host Extensions for IP Multicasting", 367 RFC 1112, August 1989. 368 [3] Meyer, D., "Administratively Scoped IP Multicast", 369 RFC 2365 (BCP 23), July, 1998. 370 [4] Alvestrand, H., "Tags for the Identification of Languages", 371 RFC 1766, March 1995. 372 [5] Handley, M., Jacobson, V., "SDP: Session Description Protocol", 373 RFC 2327, April 1998. 374 [6] Estrin, D., Handley, M., Thaler, D., 375 "The Internet Multicast Address Allocation Architecture", 376 Work-in-Progress, Internet-Draft "draft-ietf-malloc-arch-01.txt", 377 May 1999. 378 [7] Kermode, R. "MADCAP Multicast Scope Nesting State Option," 379 Work-In-Progress, Internet-Draft 380 "draft-ietf-malloc-madcap-nest-opt-01.txt", April 1999. 382 9. Author's Address 384 Ross Finlayson, 385 Live Networks, Inc. (LIVE.COM) 386 email: finlayson@live.com 387 WWW: http://www.live.com/