Group Address Allocation Protocol (GAAP)

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 13 October 2023.¶

Copyright Notice

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶

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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

4. GAAP Message Format

At this time, there is a single message called the Claim message with type value 1. Type value of 0 is reserved. The Claim message is sent in a UDP checksummed packet where the source port is ephemeral and chosen by the sender and the destination port is a well-known port allocated by IANA. GAAP can work behind NAT and firewall devices as long as the GAAP destination port is permitted through filters.¶

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |Type=1 |              Reserved                 | Record Count  |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                       0xAAAAAAAA Marker                       |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                  IPv4 Multicast Group Address                 | \
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  \
    |                                                               |    R
    |                        IPv6 Multicast                         |    e
    |                         Group Address                         |    c
    |                                                               |    o
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    r
    |                          Timestamp                            |    d
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+   /
    |                          Group Name ...                       |  /
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ /
    |                             ...                               |/
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Packet field descriptions:

Type=1:

Claim Message¶

Reserved:

Set to 0 and ignored on receipt.¶

Record Count:

The number of records in this Claim message.¶

Marker:

The fixed bit pattern of 0xAAAAAAAA is required to be set by the sender. The receiver verifies the marker to be 0xAAAAAAAA. If it is not, the packet is dropped. The Marker field is used to indicate to a receiver that the packet may be encrypted. See Section 7 for details on encrypting GAAP messages.¶

Record field descriptions:

IPv4 Multicast Group Address:

a 32-bit multicast address in network byte order [RFC1112]. If all bits are set to 0, there is no IPv4 address being allocated and claimed.¶

IPv6 Multicast Group Address:

a 128-bit multicast address in network byte order [RFC4291]. If all bits are set to 0, there is no IPv6 address being allocated and claimed.¶

Timestamp:

Standard epoch UTC timestamp according to [RFC8536].¶

Group Name:

A variable length group name the multicast application uses. It is in ASCII format [RFC0020]. The string is terminated with a null character.¶

5. GAAP API

The GAAP API has the following API calls a multicast application will use. A multicast application imports the library before using it in its code logic. This section documents a python library.¶

        import gapp

        status = gapp.init(app_callback_func)
        if (status == False):
            print("error")
            exit(1)
        #endif

        def app_callback_func(group_name, group_address)
            print("Group name {} changed to group address {}". \
                format((group_name, group_address))
        #enddef

        import gapp

        group_name = "my-audio-group"

        group_address = gapp.allocate(group_name)
        if (group_address == None):
            print("error")
            exit(1)
        #endif

        print("Name {} allocated address {}".format(group_name, group_address))

        import gapp

        group_address = gapp.allocate("my-audio-group")

        status = gapp.release(group_address)
        if (status == False):
            print("error")
            exit(1)
        #endif

        print("Released address {}".format(group_address))

        import gapp

        #
        # Initialize the GAAP API with no callback function. Return if errored.
        #
        if (gapp.init() == False):
            print("error")
            exit(1)
        #endif

        #
        # Do multicast work by allocating, sending, and receiving group addresses.
        #
        ...

        #
        # Application shutting down. No longer need to run GAAP on local node.
        #
        gaap.close()

6. Detail Protocol Operation

        hash = sha256(group_name)
        low_bits = hash & 0xffffffff
        if (v4):
            group_address = 0xe0000000 | (low_bits & 0x007fffff)
        #endif
        if (v6):
            group_address = 0xff0e...0000 | low_bits
        #endif
        return(group_address)

        for append in ["+1", "+2", "+3"]:
            hash = sha256(group_name + append)
            group_address = make_group_from_hash(hash)
            collision = send_claim(group_address)
            if (collision == False): return
        #endfor
        print("Collision limit reached")

7. Security Considerations

It is strongly suggested that the GAAP protocol run over an encrypted multicast channel. The encryption algorithm and key management procedure is not specified in this document. The message Marker is used to indicate if the packet is sent in plaintext or ciphertext. If the Marker is not set to 0xAAAAAAAA and the receiver does not have a shared-key configured, the message MUST be dropped.¶

An open-source GAAP implementation exists where ChaCha20 [RFC7539] is used to encrypt GAAP messages. The implementation's key management procedure is a simple shared key that is configured with the application.¶

At this time there is no dynamic rekeying procedure and is left for future work. Therefore, all nodes must be manually rekeyed when a node is removed from the encrypted channel.¶

The following attack threats may exist with possible mitigation techniques:¶

• Even when an encrypted channel is used, a bad actor could be claiming a group address not derived from one of the group name inputs used for the Acceptable Group Hash List (see Definition of Terms section). Cooperating nodes should ignore such messages and not try to send Claim messages to correct the bad actor node.¶
• A bad actor could send an invalid timestamp giving it tie-breaking priority when a group address collision occurs. If the group address has been prior claimed by another node with a timestamp earlier than the invalid timestamp, cooperating nodes should put the bad actor node on a bad-actor list and ignore future messages from it. If the group name has not been claimed yet, the timestamp will be accepted only if earlier than the current time for the receiving node.¶
• A bad actor could send messages too often and is not adhering to the random delay or periodic timer procedures in this document. When this occurs, cooperating nodes should start ignoring messages from the bad actor node and not reset or cancel timers, or send triggered Claim messages¶

Authors' Addresses