UDP Transport

Lightweight, connectionless transport protocol implementation intended for low-latency message delivery.

UDP in MapsMessaging is stateless by design. Any reliability, ordering, or security guarantees must be layered on top.

---

Features

• Low overhead, connectionless transport
• Minimal latency
• No per-connection state
• Optional message authentication using HMAC

---

Limitations (Read This)

• No delivery guarantees
• No ordering guarantees
• Packets may be duplicated, dropped, or reordered
• Source address can be spoofed unless authenticated
• Security is opt-in via HMAC configuration

If you need guaranteed delivery or ordering, use TCP-based transports.

---

Basic Configuration

transport:
  udp:
    type: udp
    port: 5683
    buffer_size: 65507

UDP-specific fields

Field	Description
type	Must be udp
port	UDP port to bind to
buffer_size	Maximum UDP payload size (default max is 65507 bytes)

---

Common endpoint fields

udp inherits common endpoint settings from EndPointConfigDTO. These fields are available on the UDP endpoint, even though some are more relevant to connection-oriented transports.

transport:
  udp:
    type: udp
    port: 5683

    discoverable: false
    selectorThreadCount: 2
    serverReadBufferSize: 10240
    serverWriteBufferSize: 10240

    proxyProtocolMode: DISABLED
    allowedProxyHosts: ""
    connectionTimeout: 5000

Fields

Field	Description
discoverable	Whether the endpoint is discoverable
selectorThreadCount	Number of selector threads
serverReadBufferSize	Server read buffer size in bytes
serverWriteBufferSize	Server write buffer size in bytes
proxyProtocolMode	Proxy Protocol support mode (DISABLED, ENABLED, REQUIRED)
allowedProxyHosts	Comma-separated list of allowed proxy source addresses (hostnames/IPs/CIDR)
connectionTimeout	Time to wait for a client to establish the connection, in milliseconds

---

Advanced Configuration

transport:
  udp:
    type: udp
    port: 5683
    buffer_size: 65507

    packetReuseTimeout: 1000
    idleSessionTimeout: 600
    hmacHostLookupCacheExpiry: 600

    hmacConfigList:
      - host: example.com
        port: 5683
        hmacAlgorithm: HmacSHA256
        hmacManager: Appender
        hmacSharedKey: "shared-secret"

---

Packet Handling Behaviour

Packet Reuse Timeout

packetReuseTimeout controls how long a received packet buffer may be reused before being discarded.

• Unit: milliseconds
• Range: 10 – 60000
• Lower values reduce memory usage
• Higher values reduce allocation pressure

packetReuseTimeout: 1000

---

Idle Session Timeout

Even though UDP is connectionless, MapsMessaging tracks logical sessions per remote host.

idleSessionTimeout defines how long a remote endpoint may remain idle before being expired.

• Unit: seconds
• Range: 60 – 1200

idleSessionTimeout: 600

---

UDP Security Model

UDP provides no inherent security. MapsMessaging optionally enforces HMAC-based packet authentication on a per-host basis.

Key Points

• HMAC validation is performed per packet
• No handshake or session negotiation
• Remote address must match an HMAC configuration
• Packets failing validation are rejected and logged
• Designed to integrate with tools like fail2ban

---

HMAC Configuration

HMAC is configured using a list of host-specific rules.

hmacConfigList:
  - host: example.com
    port: 5683
    hmacAlgorithm: HmacSHA256
    hmacManager: Appender
    hmacSharedKey: "shared-secret"

Fields

Field	Description
host	Remote host name or IP address
port	Remote UDP port
hmacAlgorithm	HMAC algorithm used to validate packets
hmacManager	Signature placement strategy
hmacSharedKey	Shared secret key

---

Signature Managers

The signature manager defines where the HMAC is placed in the packet.

Manager	Behaviour
Appender	Signature appended to the end of the packet
Prepender	Signature prepended to the start of the packet

Both sender and receiver must use the same manager.

---

Supported HMAC Algorithms

The following algorithms are supported via the Java Cryptography API and loaded dynamically at runtime.

Algorithm	Description
HmacSHA256	SHA-256 based HMAC (recommended)
HmacSHA384	SHA-384 based HMAC
HmacSHA512	SHA-512 based HMAC

Availability depends on the underlying JVM security provider.

---

Packet Validation and Logging

Packets failing HMAC validation generate structured log entries of the form:

Packet integrity verification failed: ip=203.0.113.9 algorithm=HmacSHA256 reason=SIGNATURE_MISMATCH packetLength=1420 signatureSize=32

These logs are intended to be consumed by monitoring tools such as fail2ban.

---

Failure Reasons

Common validation failure reasons include:

Reason	Meaning
SIGNATURE_MISMATCH	Packet was modified or forged
PACKET_TOO_SHORT	Packet shorter than required signature size
SIGNATURE_MISSING	Signature could not be extracted
NOT_INITIALISED	HMAC configuration error
INTERNAL_ERROR	Unexpected processing failure

Only SIGNATURE_MISMATCH should normally be considered malicious.

---

Security Notes

• HMAC protects integrity and authenticity, not confidentiality
• Source addresses can be spoofed; HMAC prevents unauthenticated injection
• Keys must be kept secret and rotated as required
• HMAC does not prevent replay attacks by itself

---

When to Use UDP + HMAC

Good fit:

• Sensor networks
• Telemetry streams
• Low-latency event ingestion

Bad fit:

• Financial transactions
• Strict ordering requirements
• Guaranteed delivery use cases

Use the right transport for the job.