< draft-ietf-malloc-api-06.txt		draft-ietf-malloc-api-07.txt >
	Network Working Group Ross Finlayson		Network Working Group Ross Finlayson
	Internet-Draft LIVE.COM		Internet-Draft LIVE.COM
	Expire in six months 1999.06.25		Expire in six months 1999.08.22
	An Abstract API for Multicast Address Allocation		An Abstract API for Multicast Address Allocation
	<draft-ietf-malloc-api-06.txt>		<draft-ietf-malloc-api-07.txt>
	1. Status of this Memo		1. Status of this Memo
	This document is an Internet-Draft and is in full conformance		This document is an Internet-Draft and is in full conformance
	with all provisions of Section 10 of RFC2026.		with all provisions of Section 10 of RFC2026.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF), its areas, and its working groups. Note that		Task Force (IETF), its areas, and its working groups. Note that
	other groups may also distribute working documents as		other groups may also distribute working documents as
	Internet-Drafts.		Internet-Drafts.
	skipping to change at line 68 ¶		skipping to change at line 68 ¶
	Server" network protocol (MADCAP) [1][7]. Alternatively, an		Server" network protocol (MADCAP) [1][7]. Alternatively, an
	"Address Allocation Server" implementation might be co-located (along		"Address Allocation Server" implementation might be co-located (along
	with one or more applications) on an end node, in which case some other,		with one or more applications) on an end node, in which case some other,
	internal, mechanism might be used to access the server. In either case,		internal, mechanism might be used to access the server. In either case,
	however, the abstract service interface (and, presumably, any specific		however, the abstract service interface (and, presumably, any specific
	APIs) would remain the same.		APIs) would remain the same.
	The remainder of this document describes the abstract interface.		The remainder of this document describes the abstract interface.
	Note that this interface is intended only for the allocation of dynamic		Note that this interface is intended only for the allocation of dynamic
	multicast addresses, as used by the normal multicast service model [2].		multicast addresses, as used by the traditional multicast service model [2].
	Future multicast service models might allocate or assign multicast		Future multicast service models might allocate or assign multicast
	addresses in other ways, but this is outside the scope of this document.		addresses in other ways, but this is outside the scope of this document.
	4. Abstract Data Types		4. Abstract Data Types
	The interface described below uses the following abstract data types:		The interface described below uses the following abstract data types:
	- AddressFamily: e.g., IPv4 or IPv6		- AddressFamily: e.g., IPv4 or IPv6
	- MulticastAddress: An actual multicast address (i.e., that could		- MulticastAddress: An actual multicast address (i.e., that could
	subsequently		subsequently
	be used as the destination of a datagram)		be used as the destination of a datagram)
	- MulticastAddressSet: A set of "MulticastAddress"es		- MulticastAddressSet: A set of "MulticastAddress"es
	- LanguageTag: The code for a (human) language, as defined in [4]		- LanguageTag: The code for a (human) language, as defined in [4]
	- Scope: An "administrative scope" [3] from which a multicast address is		- Scope: An "administrative scope" [3] from which multicast addresses
	to be allocated. Each scope is a "MulticastAddressSet",		are to be allocated. Each scope is a "MulticastAddressSet",
	with an associated set of (character-string) names - indexed by		with an associated set of (character-string) names - indexed by
	"LanguageTag". (Each language tag has at most one corresponding		"LanguageTag". (Each language tag has at most one corresponding
	name,		name,
	per scope.) For each scope, a (language tag, name) pair may be		per scope.) For each scope, a (language tag, name) pair may be
	defined to be the 'default' name for this scope. (See the section		defined to be the 'default' name for this scope. (See the section
	"Querying the name of a scope" below.)		"Querying the name of a scope" below.)
	(An implementation of this abstract data type might also include		(An implementation of this abstract data type might also include
	other		other
	information, such as a default TTL for the scope.)		information, such as a default TTL for the scope.)
	- Time: An (absolute) event time. This is used for specifying the		- Time: An (absolute) event time. This is used for specifying the
	"lifetime" of a multicast address: the period of time during which		"lifetime" of multicast addresses: the period of time during which
	an		allocated multicast addresses are guaranteed to be available.
	allocated multicast address is guaranteed to be availabile. (It is		(It is also used to specify the desired start time for an
	also used to specify the desired start time for an
	"advance allocation".)		"advance allocation".)
	Note that a concrete API might prefer to specify some of these		Note that a concrete API might prefer to specify some of these
	times as relative times (i.e., relative to the current time-of-day),		times as relative times (i.e., relative to the current time-of-day),
	rather than absolute time. (Relative times have the advantage of		rather than absolute time. (Relative times have the advantage of
	not requiring clock synchronization.)		not requiring clock synchronization.)
	- Lease: A compound data type that describes the result of a (successful)		- Lease: A compound data type that describes the result of a (successful)
	multicast address allocation. It consists of:		multicast address allocation. It consists of:
	- [MulticastAddressSet] The set of addresses that were allocated;		- [MulticastAddressSet] The set of addresses that were allocated;
	- [AddressFamily] The address family of these addresses		- [AddressFamily] The address family of these addresses
	- [Time] The lifetime of these addresses (the same for each address)		- [Time] The lifetime of these addresses (the same for each address)
	- [Time] The "start time" of the allocation. (See the discussion of		- [Time] The "start time" of the allocation. (See the discussion of
	"advance allocation" below.)		"advance allocation" below.)
	(A concrete API would likely also include a		(A concrete API would likely also include a
	MADCAP "Client Identifier" [1].)		MADCAP "Lease Identifier" [1].)
	- NestingRelationship: A binary data type that describes whether		- NestingRelationship: A binary data type that describes whether
	or not two scopes nest. Two scopes nest if traffic sent		or not two scopes nest. Two scopes nest if traffic sent
	sent to a multicast group within one scope could be seen		sent to a multicast group within one scope could be seen
	by all hosts present within the other scope were they to		by all hosts present within the other scope were they to
	join the multicast group within the first scope. This value		join the multicast group within the first scope. This value
	would be "False" for overlapping scopes where only some		would be "False" for overlapping scopes where only some
	(or none) of the hosts within the second scope could see		(or none) of the hosts within the second scope could see
	traffic sent to an address due to the presence of an		traffic sent to an address due to the presence of an
	administratively scoped boundary. In cases where the first		administratively scoped boundary. In cases where the first
	and second scopes are topologically identical this value		and second scopes are topologically identical this value
	would be "True."		would be "True."
	- Status: A result code.		- Status: A result code.
	5. The Abstract Interface		5. The Abstract Interface
	Allocating a multicast address:		5.1 Allocating multicast addresses:
	alloc_multicast_addr(in AddressFamily family,		alloc_multicast_addr(in AddressFamily family,
	in Scope scope,		in Scope scope,
	in Integer minDesiredAddresses,		in Integer minDesiredAddresses,
	in Integer maxDesiredAddresses,		in Integer maxDesiredAddresses,
	in Time minDesiredStartTime,		in Time minDesiredStartTime,
	in Time maxDesiredStartTime,		in Time maxDesiredStartTime,
	in Time minDesiredLifetime,		in Time minDesiredLifetime,
	in Time maxDesiredLifetime,		in Time maxDesiredLifetime,
	out Lease multicastAddressSetLease,		out Lease multicastAddressSetLease,
	out Status status)		out Status status)
	skipping to change at line 148 ¶		skipping to change at line 147 ¶
	(the size of this set is in the range		(the size of this set is in the range
	[minDesiredAddresses, maxDesiredAddresses]) within the given address		[minDesiredAddresses, maxDesiredAddresses]) within the given address
	family and scope, and within a given range of desired		family and scope, and within a given range of desired
	lifetimes. ("minDesiredStartTime" and "maxDesiredStartTime" are		lifetimes. ("minDesiredStartTime" and "maxDesiredStartTime" are
	used to specify "advance allocation"; this is described in more		used to specify "advance allocation"; this is described in more
	detail below.)		detail below.)
	If the address allocation succeeds, the result is returned in		If the address allocation succeeds, the result is returned in
	"multicastAddressSetLease" (with "status" = OK).		"multicastAddressSetLease" (with "status" = OK).
	A "best-effort" attempt will be made to maintain multicast routing		During the lifetime of this lease, the allocation service will
	for the allocated multicast addresses during their lifetime, even if
	there are topology changes (such as a change of upstream provider)
	during this time. Also, during this time, the allocation service
	will
	make a "best-effort" attempt to not allocate any of these addresses		make a "best-effort" attempt to not allocate any of these addresses
	to others. (However, once an address's lifetime has expired, it can		to others. (However, once the lease's lifetime has expired, any of
	be allocated to others.)		its addresses can be allocated to others.)
	Note that multicast addresses are allocated for a limited lifetime.		Multicast addresses are allocated for a limited lifetime.
	An application may attempt to extend this lifetime, but this		An application may attempt to extend this lifetime, but this
	operation may fail. Therefore, an application must be prepared		operation may fail. Therefore, an application must be prepared
	for the possibility it will not be able to use the same addresses		for the possibility it will not be able to use the same addresses
	for as long as it desires. In particular, the application must		for as long as it desires. In particular, the application must
	be prepared to either quit early (because its original multicast		be prepared to either quit early (because its original multicast
	address assignments have expired), or, alternatively, to		address assignments have expired), or, alternatively, to
	occasionally		occasionally
	'renumber' its multicast addresses (in some application or		'renumber' its multicast addresses (in some application or
	higher-level-protocol dependent way), by making a new allocation.		higher-level-protocol dependent way), by making a new allocation.
	However, because of the guarantee noted above, if an application		However, if an application needs to consider 'renumbering', it will
	needs		always know this in advance, at the time it acquired its current
	to 'renumber', it will always know this in advance, at the time it		address(es) - by checking the lifetime in the returned lease.
	acquired its current address(es). An application will never need		An application will never need to be notified asynchronously of
	to be notified asynchronously of the need to 'renumber'.		the need to 'renumber'.
	Possible errors:		Possible errors:
	- bad address family		- bad address family
	- bad scope		- bad scope
	- bad desired number of addresses (e.g., max < min)		- bad desired number of addresses (e.g., max < min)
	- bad desired lifetimes (e.g., max < min)		- bad desired lifetimes (e.g., max < min)
	- errors with the two "start time" parameters (see		- errors with the two "start time" parameters (see
	"Advance allocation" below)		"Advance allocation" below)
	- no addresses can be allocated (for the requested		- no addresses can be allocated (for the requested
	parameters)		parameters)
	skipping to change at line 202 ¶		skipping to change at line 197 ¶
	multicast address allocation will probably include additional,		multicast address allocation will probably include additional,
	specialized variants of this general allocation operation. For		specialized variants of this general allocation operation. For
	instance, it may include separate operations for:		instance, it may include separate operations for:
	- allocating only a single address		- allocating only a single address
	(i.e., minDesiredAddresses = maxDesiredAddresses = 1);		(i.e., minDesiredAddresses = maxDesiredAddresses = 1);
	- (attempting to) allocate an address with a single, fixed		- (attempting to) allocate an address with a single, fixed
	lifetime (i.e., minDesiredLifetime = maxDesiredLifetime);		lifetime (i.e., minDesiredLifetime = maxDesiredLifetime);
	- (attempting to) allocate an address for immediate use		- (attempting to) allocate an address for immediate use
	(i.e., minDesiredStartTime = maxDesiredStartTime = 'now')		(i.e., minDesiredStartTime = maxDesiredStartTime = 'now')
	Changing multicast addresses' lifetime:		5.2 Changing multicast addresses' lifetime:
	change_multicast_addr_lifetime(in Lease multicastAddressSetLease,		change_multicast_addr_lifetime(in Lease multicastAddressSetLease,
	in Time minDesiredLifetime,		in Time minDesiredLifetime,
	in Time maxDesiredLifetime,		in Time maxDesiredLifetime,
	out Time lifetime)		out Time lifetime)
	This operation attempts to change the lifetime of previously		This operation attempts to change the lifetime of previously
	allocated multicast addresses. Unless an error occurs, it returns		allocated multicast addresses. Unless an error occurs, it returns
	the new lifetime (which might remain unchanged).		the new lifetime (which might remain unchanged).
	Possible errors:		Possible errors:
	- bad address family		- bad address family
	- bad durations (e.g., max < min)		- bad durations (e.g., max < min)
	- the addresses' lifetime could not be changed		- the addresses' lifetime could not be changed
	(and the existing lifetime was not in the requested range		(and the existing lifetime was not in the requested range
	[minDesiredLifetime,maxDesiredLifetime])		[minDesiredLifetime,maxDesiredLifetime])
	- the addresses were not ones that we[*] had allocated		- the addresses were not ones that we had allocated
	(or they have already expired)		(see section 5.9) - or they have already expired
	Deallocating multicast addresses:		5.3 Deallocating multicast addresses:
	deallocate_multicast_addr(in Lease multicastAddressSetLease)		deallocate_multicast_addr(in Lease multicastAddressSetLease)
	This operation attempts to deallocate previously allocated		This operation attempts to deallocate previously allocated
	multicast addresses.		multicast addresses.
	Possible errors:		Possible errors:
	- bad address family		- bad address family
	- the addresses were not ones that we[*] had allocated		- the addresses were not ones that we had allocated
	(or they have already expired)		(or they have already expired)
	Querying the set of usable multicast address scopes:		5.4 Querying the set of usable multicast address scopes:
	get_multicast_addr_scopes(in AddressFamily family,		get_multicast_addr_scopes(in AddressFamily family,
	out "set of" Scope)		out "set of" Scope)
	This operation returns the set of administrative multicast address		This operation returns the set of administrative multicast address
	scopes that are defined for this node.		scopes that are defined for this node.
	Possible errors:		Possible errors:
	- bad address family		- bad address family
	Querying the name of a scope:		5.5 Querying the name of a scope:
	get_scope_name(in Scope scope,		get_scope_name(in Scope scope,
	in LanguageTag language,		in LanguageTag language,
	out String name,		out String name,
	out LanguageTag languageForName)		out LanguageTag languageForName)
	This operation returns a character-string name for a given scope.		This operation returns a character-string name for a given scope.
	If the scope has a name in the specified "language", then this name		If the scope has a name in the specified "language", then this name
	(and language) is returned. Otherwise, the scope's default		(and language) is returned. Otherwise, the scope's default
	(language, name) pair is returned.		(language, name) pair is returned.
	Possible errors:		Possible errors:
	- bad scope		- bad scope
	Querying the nesting state of known usable multicast address scopes:		5.6 Querying the nesting state of known usable multicast address scopes:
	get_scope_nesting_state(in "set of" Scope,		get_scope_nesting_state(in "set of" Scope,
	out "array of" NestingRelationship)		out "matrix of" NestingRelationship)
	Possible errors:		Possible errors:
	- bad scope.		- bad scope.
	- nesting state undetermined at this time.		- nesting state undetermined at this time.
	This operation would return an array that shows the		This operation would return a matrix that shows the
	current nesting relationships between the supplied		current nesting relationships between the supplied
	set of scopes which would have previously been supplied		set of scopes which would have previously been supplied
	via the get_multicast_addr_scopes(...) function.		via the get_multicast_addr_scopes(...) function.
	Querying the set of scopes that a given scope is known to nest inside:		5.7 Querying the set of scopes that a given scope is known to nest inside:
	get_larger_scopes(in Scope,		get_larger_scopes(in Scope,
	out "set of" Scope)		out "set of" Scope)
	This operation returns the set of administrative multicast		This operation returns the set of administrative multicast
	address scopes that are known to encompass the supplied		address scopes that are known to encompass the supplied
	Scope.		Scope.
	Possible errors:		Possible errors:
	- bad scope.		- bad scope.
	- nesting state undetermined at this time.		- nesting state undetermined at this time.
	Querying the set of scopes that are known to nest inside a given scope:		5.8 Querying the set of scopes that are known to nest inside a given scope:
	get_smaller_scopes(in Scope,		get_smaller_scopes(in Scope,
	out "set of" Scope)		out "set of" Scope)
	This operation returns the set of administrative multicast		This operation returns the set of administrative multicast
	address scopes that are known to nest inside the supplied		address scopes that are known to nest inside the supplied
	Scope (NB this would include those scopes that are		Scope (NB this would include those scopes that are
	topologically identical to the supplied scope).		topologically identical to the supplied scope).
	Possible errors:		Possible errors:
	- bad scope.		- bad scope.
	- nesting state undetermined at this time.		- nesting state undetermined at this time.
	[*] The decision as to who is allowed to deallocate (or change the lifetime		5.9 Note:
			The decision as to who is allowed to deallocate (or change the lifetime
	of) a previously allocated multicast address set lease is		of) a previously allocated multicast address set lease is
	implementation-specific, and depends upon the security policy of the host		implementation-specific, and depends upon the security policy of the host
	system. Thus it is not specified in this abstract API. One possible		system. Thus it is not specified in this abstract API. One possible
	starting point, however, is the following:		starting point, however, is the following:
	A previously allocated multicast address can be deallocated (or have		A previously allocated multicast address can be deallocated (or have
	its lifetime queried or changed) by the same "principal", and on the		its lifetime queried or changed) by the same "principal", and on the
	same node, as that which originally allocated it. ("principal"		same node, as that which originally allocated it. ("principal"
	might,		might,
	for example, be a "user" in the host operating system.)		for example, be a "user" in the host operating system.)
	Advance allocation		5.10 Advance allocation
	==================		=======================
	By specifying "minDesiredStartTime = maxDesiredStartTime = 'now'",		By specifying "minDesiredStartTime = maxDesiredStartTime = 'now'",
	the address allocation operation - "alloc_multicast_addr" - described above		the address allocation operation - "alloc_multicast_addr" - described above
	can be used to request a set of multicast addresses that can be used		can be used to request a set of multicast addresses that can be used
	*immediately* (and until their lifetime expires). During this whole time,		*immediately* (and until their lifetime expires). During this whole time,
	the addresses are not available for allocation to others.		the addresses are not available for allocation to others.
	It is also possible - using the "minDesiredStartTime" and		It is also possible - using the "minDesiredStartTime" and
	"maxDesiredStartTime" parameters - to allocate multicast addresses		"maxDesiredStartTime" parameters - to allocate multicast addresses
	*in advance* - i.e., so that they have a future "start time" as well as		*in advance* - i.e., so that they have a future "start time" as well as
	an expiration time. Before the start time, the multicast addresses may		an expiration time. Before the start time, the multicast addresses may
	be allocated to others.		be allocated to others.
	Advance allocation is convenient for allocating addresses for events that		Advance allocation is convenient for allocating addresses for events that
	begin far in the future - e.g., several weeks or months away. Without		begin far in the future - e.g., several weeks or months away. Without
	advance allocation, it would be necessary to reserve an address for a long		advance allocation, it would be necessary to allocate addresses for a long
	period of time - even when it will not be used. Such a request would not		period of time - even when it will not be used. Such a request would not
	only be a wasteful use of the multicast address space, but it may also be		only be a wasteful use of the multicast address space, but it may also be
	difficult to implement (especially since address allocations are expected		difficult to implement (especially since address allocations are expected
	to remain valid in spite of topology changes).		to remain valid in spite of topology changes).
	Advance allocation requests can produce the following errors (in addition to		Advance allocation requests can produce the following errors (in addition to
	those defined earlier):		those defined earlier):
	- bad start time durations (e.g., max < min)		- bad start time durations (e.g., max < min)
	- requested start times conflict with requested lifetimes		- requested start times conflict with requested lifetimes
	(i.e., min start time > max lifetime)		(i.e., min start time > max lifetime)
	skipping to change at line 343 ¶		skipping to change at line 339 ¶
	in Time maxDesiredStartTime,		in Time maxDesiredStartTime,
	out Time startTime)		out Time startTime)
	This operation attempts to change the start time of previously		This operation attempts to change the start time of previously
	allocated multicast addresses. Unless an error occurs, it returns		allocated multicast addresses. Unless an error occurs, it returns
	the new start time (which might remain unchanged).		the new start time (which might remain unchanged).
	Possible errors: the same as "change_multicast_addr_lifetime"		Possible errors: the same as "change_multicast_addr_lifetime"
	6. Security Considerations		6. Security Considerations
	As noted in point [*] above, each implementation of this abstract API should		As noted in section 5.9 above, each implementation of this abstract API
	define a security policy that specifies when (and by whom) a previously		should define a security policy that specifies when (and by whom)
	allocated multicast address can be deallocated (or queried, or have its		previously allocated multicast addresses can be deallocated (or queried,
	lifetime changed).		or have their lifetime changed).
	Because multicast addresses are a finite resource, there is a potential for		Because multicast addresses are a finite resource, there is a potential for
	a "denial of service" attack by allocating a large number of multicast		a "denial of service" attack by allocating a large number of multicast
	addresses without deallocating them. Preventing such an attack, however,		addresses without deallocating them. Preventing such an attack, however,
	is not the role of the API, but rather by the underlying MAAS ("Multicast		is not the role of the API, but rather by the underlying MAAS ("Multicast
	Address Allocation Server(s)" [6]).		Address Allocation Server(s)" [6]).
	7. Acknowledgements		7. Acknowledgements
	Many thanks to other participants in the "MALLOC" working group		Many thanks to other participants in the "MALLOC" working group
	- in particular Steve Hanna, Dave Thaler , and Roger Kermode - for their		- in particular Steve Hanna, Dave Thaler, Roger Kermode,
	valuable comments.		and Pavlin Radoslavov - for their valuable comments.
	8. References		8. References
	[1] Patel, B., Shah, M., Hanna, S.,		[1] Patel, B., Shah, M., Hanna, S.,
	"Multicast Address Dynamic Client Allocation Protocol (MADCAP)",		"Multicast Address Dynamic Client Allocation Protocol (MADCAP)",
	Work-in-Progress, Internet-Draft "draft-ietf-malloc-madcap-05.txt",		Work-in-Progress, Internet-Draft "draft-ietf-malloc-madcap-06.txt",
	May, 1999.		August, 1999.
	[2] Deering, S., "Host Extensions for IP Multicasting",		[2] Deering, S., "Host Extensions for IP Multicasting",
	RFC 1112, August 1989.		RFC 1112, August 1989.
	[3] Meyer, D., "Administratively Scoped IP Multicast",		[3] Meyer, D., "Administratively Scoped IP Multicast",
	RFC 2365 (BCP 23), July, 1998.		RFC 2365 (BCP 23), July, 1998.
	[4] Alvestrand, H., "Tags for the Identification of Languages",		[4] Alvestrand, H., "Tags for the Identification of Languages",
	RFC 1766, March 1995.		RFC 1766, March 1995.
	[5] Handley, M., Jacobson, V., "SDP: Session Description Protocol",		[5] Handley, M., Jacobson, V., "SDP: Session Description Protocol",
	RFC 2327, April 1998.		RFC 2327, April 1998.
	[6] Estrin, D., Handley, M., Thaler, D.,		[6] Estrin, D., Handley, M., Thaler, D.,
	"The Internet Multicast Address Allocation Architecture",		"The Internet Multicast Address Allocation Architecture",
End of changes. 28 change blocks.
	48 lines changed or deleted		44 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/