Wire-format Alerting for Risk Notification

2.1. Issues of Existing Solutions

• Lack of efficient internationalization¶

  • The size of messages multiply with internationalization.¶

• Unbounded¶

  • On systems that lack proper amounts of available memory, CAP may overwhelm the chip, given that its length is not hard-capped.¶

• Centralized¶

  • Even though the networking around the alert origin may be robust, bottlenecks may exist at any point in between the central origin and client.¶

  • Physical interruptions of the network may cause connections to fault, and may require an expensive route change.¶

  • The amount of connections the origin can juggle simultaneously limits the amount of clients that can receive CAP XML alerts.¶

• Complex¶

  • XML is hierarchical, and you need to parse the whole tree to fetch information safely.¶

  • CAP is too flexible and tolerant of duplicate fields in arbitrary order.¶

  • Pushing multimedia through emergency pipelines increases the risk of corruption and/or incomplete messages.¶

• Insecure¶

  • No legitimate enforcement on signing.¶

• Demanding¶

  • Memory requirement is theoretically unbound due to CAP being unbound.¶

  • Media interpretation requires mature, complex libraries.¶

  • Realistically requires a whole OS to be running to make use of CAP.¶

2.2. Design Goals

• Minimal alert-plane packet¶

  • Single UDP datagram¶

  • Signed, verifiable, immutable¶

• Best-effort propagation¶

  • Time-bounded spread¶

  • Geographic advisory bounds¶

• Two-plane architecture¶

  • Alert-plane: eager, proactive, stateless¶

  • Info-plane: lazy, optional (not specified here)¶

• Compatibility¶

  • Be easily convertible from existing formats (e.g., CAP)¶

  • Allow future extensions without breaking existing implementations¶

• Strong authenticity¶

  • Alerts are valid only if signed by an Alert Origin key¶

  • Relay "trust" does not imply alert validity¶

• no_std / zero-copy friendly¶

  • Fixed layouts¶

  • Explicit bounds¶

  • No required allocation¶

• MTU safety¶

  • Recommended UDP payload <= 1200 bytes¶

• Lightweight¶

  • Be able to run on minimal hardware¶

3.1. Normative Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3.2. Versioning

WARN uses a two-level versioning scheme to distinguish wire incompatibility from backward-compatible extensions.¶

• Major version (version_major)¶

  • A change in major version indicates wire-incompatible changes.¶

  • If version_major is greater than the highest version supported by the implementation, the packet MUST NOT be fully interpreted.¶

  • Implementations MAY parse only the common prefix for the purposes of safe rejection, logging, or routing, but MUST treat the packet as unsupported.¶

  • No compatibility guarantees are provided across major versions.¶

  • If version_major is zero, the packet is considered invalid.¶

• Minor version (version_minor)¶

  • A change in minor version indicates a backward-compatible extension within the same major version.¶

  • Minor version updates MUST NOT change the meaning of any field defined in the current major version.¶

  • Minor version updates MAY:¶

    • define new flag bits (previously RESERVED),¶

    • define new TLV types,¶

    • define new hazard_minor values,¶

    • add new semantics that can be safely ignored by older implementations.¶

  • However, keeping up to date is strongly recommended.¶

  • Receivers MUST ignore unknown flag bits and unknown TLV types.¶

3.3. Time

• UNIX seconds (UTC), u64.¶

• Method of syncing time is dependent on hardware and medium.¶

3.4. Geographic Encoding

Latitude and longitude are signed i32 in 100-nanodegree units (1e-7 degrees).¶

Ranges:¶

• latitude: -900_000_000 ... +900_000_000¶

• longitude: -1_800_000_000 ... +1_800_000_000¶

3.5. Distance

Distance is encoded as 10-meter units:¶

• Stored value: radius_10m (u16)¶

• Real meters: affected_radius_m = radius_10m x 10¶

• Used for propagation decisions (see Section 10.2)¶

• A value of 0 indicates "unknown" or "see polygon TLV"¶

3.6. Authority Model

• ALERT validity requires:¶

  1. A valid Ed25519 signature, AND¶

  2. The signing key being present in the local Origin Registry (registry format defined in Section 18).¶

• On-wire packets DO NOT embed public keys in v1.0.¶

• The packet identifies the signing key by origin_key_id.¶

6.1. Fixed ALERT Fields

Field descriptions:¶

• timestamp_s: The time this alert was issued¶

• event_id: The root ID that this event has. Subsequent updates or queries to a database will utilize this specific key.¶

• ttl_s: The baseline amount of time relays SHOULD propagate for.¶

• hazard_major, hazard_minor, urgency, certainty, response: Specified in Section 7.¶

• onset_s: When the alert becomes active¶

• expiry_s: When the alert expires¶

• effective_time_s: When the event actually occurred or will occur¶

• epicenter_lat, epicenter_lon: Epicenter coordinates in 100-nanodegree units (see Section 3.4).¶

• radius_10m: Affected radius used for propagation decisions (see Section 10.2)¶

Deriving signed_tlv bounds: The signed TLV block has no explicit length field. Bounds are derived from the transport-provided packet length:¶

• signed_tlv starts at offset 0x40¶

• signed_tlv ends at packet_len - 68 (68 = 4 origin_key_id + 64 signature)¶

• Receivers MUST validate: packet_len >= 0x40 + 68 (i.e., packet_len >= 132)¶

6.2. Signature Block

Immediately follows signed_tlv:¶

• Algorithm: Ed25519 [RFC8032] (required)¶

• Signed region: [0x00, packet_len - 64)(covers Common Prefix + ALERT fields + signed_tlv + origin_key_id).¶

• Receivers MUST resolve origin_key_id via the Origin Registry and reject if not present.¶

• Receivers MUST verify the signature before acting on any ALERT field.¶

8.1. CANCEL Semantics

A packet with the CANCEL flag set cancels the event identified by event_id.¶

• CANCEL packets MUST carry a seq strictly greater than the highest previously accepted seq for that event.¶

• Upon accepting a CANCEL, receivers MUST immediately expire the event and cease acting on it.¶

• The CANCEL's deduplication entry MUST persist in the replay cache for at least ttl_s seconds measured from the CANCEL packet's own timestamp_s. This prevents late-arriving retransmissions of the original alert from slipping through after the CANCEL entry expires.¶

10.1. Time-Based TTL

The ttl_s field represents how many seconds the packet is permitted to spread.¶

Conceptual rule:¶

age_s = now_s - timestamp_s
if age_s > ttl_s -> SHOULD NOT forward

10.2. Geographic Bounding

• Relays SHOULD drop packets outside radius_10m x 10 meters.¶

  • If a relay does not know its own location, it MUST propagate.¶

10.3. Forwarding Strategy

• Stateless fan-out¶

• Medium-dependent congestion control¶

10.4. Forwarding Exceptions

Under any of the conditions specified below, alerts MAY be propagated regardless of ttl and geographic bounding.¶

• When a relay has a record of that specific event ID in its cache and it receives an alert with higher seq.¶

• When a relay is unsure of its own time, or if it may have a skewed clock for any reason.¶

• When a transport medium is known to have a slow transport speed.¶

11.1. Fixed Headers

The kind field identifies the packet type. All non-ALERT packets share this header immediately after the Common Prefix.¶

Receivers MUST silently drop any packet whose kind is unknown or whose kind belongs to a different transport's range.¶

11.2. WARN Reserved Ranges

The table of reservations for WARN 1.0 is as follows.¶

12.1. Advisory Signature Block

Immediately follows the kind-specific payload:¶

12.2. Advisory Kind Assignments

12.3. ADVISORY_NEW (0x0001)

Registers a new alert origin. Receivers MUST add the entry to their local registry and update their stored registry version to new_registry_version. In the case nodes receive a valid ADVISORY_NEW packet that collides with the current registry, nodes MUST drop that packet and refuse update, and SHOULD do a full resync of its local origin registry.¶

Minimum packet size: 8 (prefix) + 2 (kind) + 44 (payload) + 64 (signature) = 118 bytes¶

12.4. ADVISORY_REVOKE (0x0002)

Emergency revocation of a compromised or rogue alert origin. Receivers MUST immediately remove the identified origin from their local registry and reject any further ALERTs signed by it, regardless of signature validity.¶

This packet SHOULD have URGENT set.¶

Minimum packet size: 8 + 2 + 12 + 64 = 86 bytes¶

12.5. ADVISORY_RETIRE (0x0003)

Planned decommission of an alert origin. Receivers MUST remove the identified origin from their local registry and update their stored registry version.¶

Unlike ADVISORY_REVOKE, retirement is planned and does not imply compromise. URGENT SHOULD NOT be set.¶

Minimum packet size: 86 bytes¶

12.6. ADVISORY_UPDATE (0x0004)

Notifies nodes of a scheduled WARN protocol update. Implementations MAY ignore it. It carries no enforcement.¶

Minimum packet size: 8 + 2 + 10 + 64 = 84 bytes¶

12.7. ADVISORY_REGISTRY_REFRESH (0x0005)

Signals that the registry has been updated and nodes SHOULD re-sync via the info-plane. Carries the authoritative current registry version so receivers can determine whether they are behind.¶

Receivers that find their local registry version behind current_registry_version SHOULD fetch the full registry from the info-plane.¶

Minimum packet size: 8 + 2 + 8 + 64 = 82 bytes¶

16.1. Relay MUST

• Bounds-check packets¶

• Resolve origin_key_id via Origin Registry¶

• Verify signature¶

• Enforce time-based TTL¶

• Enforce replay protection¶

• Forward immutable packets¶

16.2. Client MUST

• Bounds-check packets¶

• Resolve origin_key_id via Origin Registry¶

• Verify signature¶

• Enforce freshness¶

18.1. Top-Level Structure

• registry_version: u64, used to manage deltas and versions. The registry version MUST monotonically increase. This MUST match the newest version that the node has obtained, either via a sync or ADVISORY.¶

18.2. Origin Entry

Each entry MUST contain:¶

• origin_key_id: integer (must fit u32)¶

• pubkey: Raw Ed25519 public key (32 bytes)¶

18.3. Required Receiver Behavior (Authorization)

Receivers MUST:¶

• Reject ALERTs if origin_key_id does not exist in the registry.¶

• Verify Ed25519 signature using the registry pubkey.¶

• Remove origins immediately upon receiving a valid ADVISORY_REVOKE or ADVISORY_RETIRE signed by the master origin.¶

22.1. WARN Hazard Codes

IANA will create the following registry:¶

Registry Name: WARN Hazard Codes¶

Registration Procedure: RFC Required¶

NOTE: The complete values of this table are TBD.¶

22.2. WARN Response

IANA will create the following registry:¶

Registry Name: WARN Response¶

Registration Procedure: RFC Required¶

22.3. WARN Urgency

IANA will create the following registry:¶

Registry Name: WARN Urgency¶

Registration Procedure: RFC Required¶

22.4. WARN Severity

IANA will create the following registry:¶

Registry Name: WARN Severity¶

Registration Procedure: RFC Required¶

22.5. WARN Certainty

IANA will create the following registry:¶

Registry Name: WARN Certainty¶

Registration Procedure: RFC Required¶

22.6. WARN Reserved Ranges

IANA will create the following registry:¶

Registry Name: WARN Reserved Ranges¶

Registration Procedure: RFC Required¶

22.7. WARN Advisory Codes

IANA will create the following registry:¶

Registry Name: WARN Advisory Codes¶

Registration Procedure: RFC Required¶

23.1. Normative References

[RFC8032]

Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, <https://www.rfc-editor.org/info/rfc8032>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

23.2. Informative References

[CAP]

Westfall, J., Jones, E., and OASIS, "Common Alerting Protocol Version 1.2", 2010, <https://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html>.

[RFC7946]

Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016, <https://www.rfc-editor.org/info/rfc7946>.