Class BeaconSeal

java.lang.Object
ai.badmonkey.agentspaces.peering.bootstrap.BeaconSeal
public final class BeaconSeal extends Object
The sealed form of a bootstrap-beacon datagram (SPEC §10.1 v0.1.19 addendum, SRAD dtls-support §3.8): for a group whose members hold a content key, the signed self-advertisement travels AEAD-sealed behind a tag that rotates every 300L seconds, so a bystander on the segment learns neither the group, the issuer, nor the endpoints, and cannot link one epoch's datagrams to the next. DTLS cannot carry a multicast send; this seals the payload and leaves the carrier alone. 
datagram = "ASB2" (4) | tag (16) | nonce (12) | AES-256-GCM(sealKey, nonce, ad = "ASB2" | tag, signedAd)
beaconKey | sealKey = HKDF-SHA-256(ikm = contentKey, salt = empty, info = "aspace-beacon-v1", 64 bytes)
tag = HMAC-SHA-256(beaconKey, "aspace-beacon-tag" | epoch as 8 bytes)[0..16)
epoch = floor(unix seconds / 300)

The opened bytes are the same signed self-advertisement a plain datagram carries, and they go through the same verification and admission.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    EPOCH_SECONDS
    The tag rotates this often.
    static final byte[]
    MAGIC
    The first four bytes of every sealed datagram.
    static final int
    OVERHEAD
    Bytes a seal adds to the advertisement.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BeaconSeal(byte[] contentKey)
    Derives the beacon keys from a group's content key.

  • Method Summary

    Modifier and Type
    Method
    Description
    static long
    epoch(Instant now)
    The beacon epoch of an instant.
    static boolean
    isSealed(byte[] datagram)
    Whether a datagram is in the sealed form.
    Optional<byte[]>
    open(byte[] datagram, Instant now)
    Opens a sealed datagram if it carries this group's tag for the current or the previous epoch; one HMAC per epoch tried, and the AEAD only on a match.
    byte[]
    seal(byte[] signedAd, Instant now)
    Seals a signed self-advertisement under the current epoch's tag.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MAGIC

      public static final byte[] MAGIC
      The first four bytes of every sealed datagram.

    • EPOCH_SECONDS

      public static final long EPOCH_SECONDS
      The tag rotates this often.
      See Also:

    • OVERHEAD

      public static final int OVERHEAD
      Bytes a seal adds to the advertisement.

  • Constructor Details

    • BeaconSeal

      public BeaconSeal(byte[] contentKey)
      Derives the beacon keys from a group's content key.
      Parameters:
      contentKey - the group's content key (32 bytes)

  • Method Details

    • isSealed

      public static boolean isSealed(byte[] datagram)
      Whether a datagram is in the sealed form.

    • epoch

      public static long epoch(Instant now)
      The beacon epoch of an instant.

    • seal

      public byte[] seal(byte[] signedAd, Instant now)
      Seals a signed self-advertisement under the current epoch's tag.
      Parameters:
      signedAd - the plain datagram's bytes
      now - the current time
      Returns:
      the sealed datagram

    • open

      public Optional<byte[]> open(byte[] datagram, Instant now)
      Opens a sealed datagram if it carries this group's tag for the current or the previous epoch; one HMAC per epoch tried, and the AEAD only on a match.
      Parameters:
      datagram - the received bytes
      now - the current time
      Returns:
      the signed self-advertisement, or empty when the tag is not this group's or the seal fails