Creating CAP Applications

From CAP Cookbook

The Common Alerting Protocol (CAP) can be used in many ways. Along with this flexibility comes the need for the builders or integrators of CAP-based applications to make some basic design decisions.

(The term "application" is used here to refer to a networked system of computers or other digital devices that exchange CAP messages in order to perform some function. The term "program" is used for individual instances of software on individual computers.)

This document is an attempt to summarize some of the key choices and trade-offs facing the designer or integrator of a CAP-based application.

Contents 1 The Challenge of Network-Centric Design 2 CAP Message Sources 2.1 Human Creation 2.2 Automated Sources 2.3 Relays, Gateways and Buffers 3 Transport 3.1 Push versus Pull 3.2 Relay versus Broadcast 3.3 Popular Real-World Options 4 Security 4.1 "Trusted Link / Trusted Node" 4.2 End-to-End Signature and Encryption 5 Updates and Cancellations 5.1 Update Messages 5.2 Cancel Messages 6 Specialized Data Extensions 6.1 Parameters 6.2 Resource Blocks 6.3 A Really Bad Idea 7 CAP Profiles 8 Geospatial Descriptions (Areas) 9 User Interfaces 10 CAP-based Activation of Devices

The Challenge of Network-Centric Design

CAP applications are inherently "network-centric"; that is, they rely on the exchange of standardized messages over a shared network. The standardization of the message enables the creative combination of diverse and sometimes unexpected devices. We can make very few assumptions about the nature of the various nodes in a CAP-based application.

This approach can seem a challenge to some IT professionals who are accustomed to a more "processor-centric" approach that emphasizes the internal optimization of local programs in a predictable environment over the standardization and interoperability of networked "peripheral" interfaces.

The ancient Internet dictum applies here: "Be strict about what you send, and tolerant about what you receive." Ultimately the burden falls to each source of CAP messages to generate messages that honor the basic structure and semantics set forth in the OASIS CAP specification. Likewise, the burden falls to each receiver of CAP messages not to break just because an otherwise-valid CAP message contained or didn't contain some expected feature that isn't mandatory under the specification.

That doesn't mean CAP can't be used in specialized or unforeseen ways. In fact, that happens all the time. CAP has built-in mechanisms for including application-specific data. But any CAP message should make at least basic sense to any CAP receiver, whether or not that receiver is aware of the usage or meaning of the application-specific bits.

CAP Message Sources

CAP messages can come from a variety of sources. Basically, though, these fall into two groups: human and automated:

Human Creation

Humans generally use some sort of on-screen form to create CAP messages. (It's certainly possible to compose the CAP XML directly using some sort of text editor, but it's not much fun.) A CAP entry form offers its human user two amenities:

1. It guides the user through the structure of the CAP message, providing a template that helps prevent omissions or oversights in message content; and,
2. It can supply pre-produced "boilerplate" content for the free-text elements of the CAP message (e.g., senderName, description or instruction) to ease the message preparation process (especially useful if the user can be expected to be under time-pressure and/or other kinds of stress.)

CAP message entry forms can range from quite literal element-by-element parallels to the CAP XML structure to very specialized data entry forms that owe their design more to the nature of the operator's job than to CAP itself. (At the extreme, a single push-button might be sufficient to trigger the creation of a complete CAP message, although at that point it might be more meaningful to think of the process as automated than manual.) Generally speaking, the more specialized the operator's duties the more customized the form can be; the more generalized the operator's responsibilities, the more the form will tend to echo the CAP message structure.

Automated Sources

Almost any CAP origination process will have some element of automation, simply because some elements of the message (e.g., the sent time and/or sender) will be below the level of detail the operator wants to deal with and are easily inserted by software. At the other extreme, automated alerting systems, sensors, telemetry and the like may generate CAP messages with complete autonomy.

In the design of such automatic systems, it's important to bear in mind that some CAP fields are specified as being for "human readable" content. Although it might be tempting to put cryptic codes or data in the description element, for example, that would violate the semantics of CAP and result in messages that would be meaningless to any consumer that didn't know that system's particular usage. (In such a case, where's the point of using CAP at all? Why not just make up your own XML format?)

A better, more CAP-compliant implementation would generate a bit of descriptive text that would make at least some basic sense to humans (e.g., "Sensor trip" in the description field) and then put the system-specific details in either a parameter element or a resource block. That way, if the message ever makes its way to some non-specialized CAP receiver, at least it won't cause confusion.

Relays, Gateways and Buffers

A special case of an automated source is one that does not actually originate CAP messages itself but merely forwards messages received from elsewhere. Such devices act both as recipients and as sources and also may perform additional processing such as filtering, routing or just storage over time.

An important consideration at such nodes is the integrity of each CAP message. A CAP message that has been modified should not be presented as the same CAP message! A modified CAP message should be presented as a new message, with its own unique sender/identifier name. It may (in fact, it probably should) include a <reference> to the original message(s). This is especially crucial when digital signatures are used, as any modification of the original message will invalidate the signature and make authentication impossible.

Transport

The CAP specification is deliberately "transport agnostic"; that is, it doesn't specify or care how CAP messages are transmitted from place to place (so long as they're transmitted accurately!) So one of the first questions the application designer has to address is, "how will we move messages around?"

Push versus Pull

A traditional way to segment the universe of data-transport schemes is by separating "push" mechanisms from ones that "pull."

Push transports send the message when the sender is ready--usually as soon as possible after the information in the message is first developed--and requires that the recipient be prepared to receive it whenever it arrives. (Radio and TV broadcasting are examples of "push" media.)

Pull mechanisms hold the message at the source until a recipient requests it by "polling" the source. (Web pages like this one are examples of a "pull" medium.)

Push systems are speedy and scalable but they also can be brittle. What happens if the receiver is offline when the message is sent? Or if there's interference at the receiving end? (One hybrid approach is the "data carousel" used in some data broadcasting systems, where the message is pushed out repeatedly over a period of time so receivers have a greater chance of catching missed or partial transmissions.)

Pull systems entail more transmission overhead, because each recipient must establish an individual connection with the source from time to time to ask "what's new?" This process is called "polling." In order not to overload the sender and/or the network, some interval of time must be allowed to pass between "polls," adding a variable delay to transmission (the average delay is half the polling interval, assuming that new messages become available at random times).

Relay versus Broadcast

Another distinction among distribution schemes has to do with whether the source serves a small group of known recipients or a larger group of unknown ones. ("Small" and "large" are relative terms here, and largely by-products of the "known/unknown" factor.)

If the source can maintain a database of known recipients, it can use that information to help preserve system privacy and to maximize the efficiency of message relay (e.g., by "batching" messages for a single recipient in a single transmission, or by "filtering" the messages it sends to a particular recipient.) And once every appropriate destination has the message, the source no longer needs to deal with it.

But as the number of recipients grows, it may become impractical for the source to maintain an up-to-date database of all legitimate recipients. In fact, in a "publication" or "broadcast" application, where the messages are made available for whoever wants them without restriction, it may not even be possible.

The broadcast approach minimizes the marginal cost of each additional recipient by foregoing such record-keeping at source. Any filtering, scheduling or optimizations have to be done at the receiving end. The source has less control, but also is less affected by variations in usage.

It's important to remember that a push transmission scheme doesn't necessarily imply a broadcast application. Broadcast distributions such as digital TV or satellite distribution can be limited to a specified audience by means of encryption; even though anyone can receive the signal, only known recipients get the decryption key. Likewise, pull schemes like RSS can be (and in fact usually are) available to the public.

Popular Real-World Options

The first generation of CAP applications have generally used familiar Web techniques for message transport:

HTTP Post: The simplest way to transmit a CAP message to an Internet server is often to submit it in the style of an ordinary webpage form. The CAP XML message can be cut-and-pasted into an actual form opened in a browser, or a program can emulate the behavior of the browser to submit a message automatically. A simple CGI, ASP or JSP program on the server side accepts the CAP message and hands it to other programs for storage or processing. An encrypted transmission (HTTPS) may be used to allow secure submission of authentication information (e.g., a user-id/password pair.)

RSS/Atom Feed: CAP messages intended for publication to a large audience over the Internet frequently are published in the form of RSS or Atom "feeds." A collection of CAP messages are made available on a standard web server along with an XML "index" file (in the RSS or Atom format) that lists the individual messages' URLs along with some simple summary of the message content. This technique has the advantage of being compatible both with automated processes and with human consumers using "feed readers" or ordinary Web browsers. For enhanced human readability, the XML of both the index and the individual CAP messages may be accompanied by a CSS stylesheet to enhance their visual presentation in browsers.

Some other, less well-known transports also have been used:

XMPP (aka "Jabber"): Designed as an open-source instant-messaging protocol, XMPP can be used to transport any kind of XML document in a "push" mode. An XMPP extension document, XEP-0127, specifies CAP messages should be transmitted over Jabber-based systems.

Data Broadcast: Various proprietary protocols for reliable delivery of data over one-way links can be used to implement "broadcast push" of CAP messages over satellite or terrestrial digital radio or TV transmissions.

In more sophisticated XML processing contexts such as "Service Oriented Architectures" two standards are available for message transmission:

EDXL-DE (PDF): The OASIS EDXL Distribution Element is a specialized "envelope" for emergency-related messages.

SOAP: The SOAP encapsulation is a widely-used mechanism for transmission and routing of all kinds of XML documents.

As other data transmission schemes evolve in the future, they may come to rival the above for efficiency and familiarity.

Security

Information security often is divided into three aspects--Confidentiality, Integrity and Authenticity--in order to take advantage of the mnemonic acronym "CIA." Although there may be dispute over details, the general outline is fairly useful:

Confidentiality refers to keeping the information private to an intended audience (although "intended by whom?" can become a complicated question sometimes.)

Integrity refers to the information remaining in its original form without distortion or interference.

Authenticity refers to being able reliably to identify the source of the information.

There are two general approaches to the security of CAP applications: Securing the channels of transmission, and adding supplementary information with the message itself.

"Trusted Link / Trusted Node"

By far the most common approach in early CAP applications has been to rely on the security of a trusted server, usually combined with SSL encryption on the input side to preserve the confidentiality of the originators' credentials.

This is a familiar technique, easily and inexpensively implemented with standard Web technologies, and it works well for simple, stand-alone applications. The issuance and updating of credentials, usually in the form of user id/password pairs, is the chief expense/labor activity.

However, this approach becomes brittle in "federated" system involving relay of messages among multiple systems, because any compromise of security (credentials, physical access to servers, "man in the middle" attacks, etc.) at any node or on any link will invalidate the entire security model.

End-to-End Signature and Encryption

A more complex but more robust approach involves digital signatures. A CAP message can be "signed" by adding a computed value to the original message, the value having been derived both from the message content and from a "private key" held by the originator. Using a corresponding "public key" for the purported originator and the received message text should provide a matching value. If so, the recipient can be confident that:

1. The message is actually from the publisher of the public key (authenticity); and,
2. The message has not been modified in transit (integrity).

Because of the "asymmetric" nature of the calculations used in public key cryptography, the digital signature does not need to be kept secret, and neither does the public key of the sender. (The sender's private key does, however.) In this way message authenticity and integrity can be verified "end to end" even if the message has been relayed over insecure links or nodes.

Although there are relatively few occasions when CAP messages need to be be kept private, a similar technique can be used for full-message encryption when required. In this case the entire message is transformed using a public key that corresponds to a private key held by the authorized recipient(s).

The OASIS CAP documents specify the use of the W3C XML-Signature and XML-Encryption recommendations for interoperable implementation of end-to-end digital signatures and encryption. The open-source Apache XML Project has published [software libraries] for implementing these recommendations in Java and C++.

Use of XML-Signature and XML-Encryption generally requires the availability of a public key infrastructure (PKI) that establishes and maintains the connection between users and their public/private key pairs. PKI services are available from a number of commercial and governmental agencies, and there are numerous commercial and open-source software packages available for implementing new ones.

An alternative approach utilizes a "web of trust" model of mutual endorsements to validate digital identities. This approach removes the need for a single "caretaker" authority as in a PKI, but introduces a degree of "relativity" to the trust model that many users, especially governmental ones, may have difficulty embracing.

Updates and Cancellations

Situations change, and things go wrong... and occasionally things even get better. So CAP provides mechanisms for updating and canceling previous messages with messages of msgType "Update" or "Cancel". Both of these message types require the use of the references element to specify what message or messages the current one is amending or canceling. Although it's not mandatory and may not always be feasible, it's a good idea to include references to all the preceding messages in case of a "chain" of updates, or at least to any of them that have not already expired.

Update Messages

An update message serves as a complete replacement for the earlier messages. That means it should have all the information, including complete Info and Area elements, not just what's changed. That's because recipient might "tune in late," that is, might receive the update after having been out of contact for awhile (or might be just now entering the targeted area) and might not have a copy of the earlier message.

Nodes that actively forward CAP messages should forward updates to everywhere they sent the previous message, and also to anyplace appropriate for the new message. That means that forwarding ("relay") nodes should buffer any messages they relay (or at least the distribution information for those messages) until those messages expire, so they can route any updates appropriately.

Nodes that do not forward but only buffer CAP messages (RSS and Atom feeds, for example) can simply remove the previous message and post the update in its place.

Nodes that process CAP messages should provide for the possibility that an update may require less or different processing than the original did. For example, an update to the forecast area for a moving storm might reach some nodes that were in the original hazard area but not in the updated one. In that case the update message can be treated in the same way as a cancellation.

Cancel Messages

A cancel message absolutely and completely negates the previous message it references. The note element may optionally be used for explaining the cancellation. Info and Area blocks are not required in cancel messages and may, in fact, create ambiguity as to the meaning and scope of the message.

As with updates, forwarding and buffering nodes have an obligation to their consumers to make the cancellation available to anyone who might have received the original message. "Push" systems should forward the cancellation to the same places they sent the original messages. "Pull" systems should delete the canceled message and post the cancellation message for a reasonable period of time to ensure that polling clients have an opportunity to pick them up. ("Reasonable" will depend on context, but in public distribution systems keeping a cancel message available for an hour might not be unreasonable.)

A cancellation can be thought of as a forced expiration, and receive-only nodes can treat a canceled message in the same way as an expired message. Ongoing activities such as automated telephone calling or siren soundings should be halted as quickly as possible.

Specialized Data Extensions

The CAP message format includes items of information deemed necessary for effective disaster warnings (PDF). However, sometimes it may be desirable to add special information related to a particular hazard or protective action. The CAP message format provides two mechanisms for including such information.

Parameters

Parameter elements can be used to add individual items of data, such as measurement values. Each parameter has a "valueName" and a "value." Although CAP 1.1 does not require that valueNames be globally unique, nor does it guarantee that information about the interpretation of valueName/value pairs will be available to recipients.

For those reasons, parameters may be used to enhance a CAP message but should never be necessary to understanding the basic import of the alert. Put another way, CAP message should make sense even without its parameter elements.

Resource Blocks

Larger blocks of data, such as additional XML documents, binary files, graphics, audio or video, can be "attached" to a CAP message using a resource element (actually a complex element or "block"). Resources can be included in one of two ways:

1. By Reference - This is the preferred method in most cases. The resource block specifies a URL from which the resource can be retrieved, along with some descriptive information about the resource's MIME type, size and a textual description. This method keeps the CAP message itself compact, and allows each recipient to determine for itself whether it needs to retrieve the attached resource (e.g., a text-only display device doesn't need to retrieve an audio file, so why waste the bandwidth?)
2. By Inclusion - If necessary, the resource may be converted to CDATA using base-64 encoding and included directly in the CAP resource block. This can increase the size of the CAP message massively, especially since base-64 encoding of binary data inherently increases the size of that data to 133% of the original. However, this method becomes necessary when using a one-way data link (such as satellite broadcast) that doesn't provide a return channel by which recipients can request supplemental data.

A Really Bad Idea

Occasionally implementers may be tempted to "overload" the semantics of the core CAP data elements in order to include specialized data without resorting to the use of CAP parameters or resources. As an example, it might be tempting simply to establish a local convention that the first or last word in the description element is actually a system-specific codeword or value that needs to be extracted and processed separately.

This is a Really Bad Idea (RBI) because it creates a unique subspecies of CAP messages that may not be fully interoperable with other CAP implementations. Messages from other sources can never be processed safely in such an environment, since their content could be misinterpreted on the basis of some local usage the sender didn't know about.

If CAP isn't what you need, please don't use CAP! CAP isn't intended to be optimal for every application; it's designed to be interoperable across many different applications. If you can't use standard CAP, it's easy enough to design your own custom XML document type, and that way you won't create confusion by promoting what are effectively different versions of CAP.

This does not mean that profiles of CAP aren't permissible.

CAP Profiles

CAP profiles are sets of additional constraints within the boundaries of the basic CAP specification. Profiles are sometimes required to specify particular data which must be included in messages in order for them to be processed fully by particular recipients. E.g., profiles have been proposed for use of CAP messages intended for distribution systems that are subject to Canadian bi-linguality laws, as well as for CAP messages intended for broadcast over the U.S. Emergency Alert System. In addition, informal profiles frequently evolve within localized warning systems, e.g., specifying command parameters used to control local features.

A message that conforms to a CAP profile will be a fully valid CAP message and should make at least basic sense to recipients that are unaware of the profile restrictions. By the same token, recipients which enforce a CAP profile should be designed to "fail gracefully" when presented with valid CAP messages that don't implement that profile.

Geospatial Descriptions (Areas)

Probably the most innovative thing about the Common Alerting Protocol is its use of flexible geospatial descriptions based on Geographic Information System technology.

In the past, alerting messages have generally been targeted either to the limited geographic coverage of the delivery system (e.g., sirens, radio transmitters) or to one or more pre-determined zones referred to by a name or code (SAME or ZIP codes, political jurisdiction names, etc.) This fixed-targeting technique has the advantage of simplicity; even when named zones are in use, their boundaries can be communicated to the target audience ahead of time.

The problem is that this doesn't match the real-world behavior of hazards. The area actually at risk from a particular hazard is variable and rarely is constrained by predetermined administrative boundaries. Thus fixed-targeting schemes are forced to offset this uncertainty with a significant level of "over-warning" to recipients that may not actually be at risk in a particular instance. The resulting "warning spill" has at least three undesirable side-effects:

1. People and activities that aren't threatened by the hazard or event may still be disrupted by the need to respond to an overly-broad warning;
2. Recurrent irrelevant warnings can cause recipients to discount future warnings (sometimes called the "cry wolf syndrome," although the problem actually has to do with the perceived irrelevance due to imprecise targeting rather than the absolute factual accuracy of the message); and,
3. As a result of 1 and 2 above, sources in possession of information about a potential hazard may hesitate to issue an alert or warning until it is too late.

CAP allows much more precise (and therefore smaller) target areas to be specified on a case-by-case basis using one or more instances of two geospatial geometries:

A circle defined by a latitude/longitude centerpoint and a radius around it.

A polygon (a regular or irregular closed shape) defined by a series of latitude/longitude corner points.

These shapes can be drawn to reflect a particular hazard instance using a computer mapping application, generated automatically by a hazard model program, or, for compatibility with older warning programs, they can simply outline some pre-determined zone or jurisdictional boundary. (A zone or jurisdiction is really just a naming convention for some pre-determined polygon.) A simple geometric calculation can then be performed by each recipient to determine whether it is in the target area for that particular alert.

Additionally, for back-compatibility with older zone-based systems, the CAP message format allows the inclusion of a geocode element, which is a valueName/value pair similar in form to a CAP parameter. This allows the inclusion of predesignated codes and names for fixed alerting boundaries. However, the CAP specification deprecates the use of geocodes by themselves in an alert, for two main reasons:

1. Reliance on geocodes alone sacrifices the flexible targeting of CAP alerts and thus one of its chief contributions to warning system effectiveness; and,
2. In order to interpret geocodes, mobile receiving devices need to carry with them details of the zone boundaries, and any local zoning scheme not built into the receiving device will be meaningless to it.

A primary obstacle to the implementation of flexible geospatial targeting appears to have been the relative unfamiliarity of geometric computations compared with simple string-matching of codes. However, simple point-in-polygon functions are available online for most major programming languages.

User Interfaces

CAP is an XML (or sometimes an ASN.1) message format for data exchange between computerized devices. As such, human users only rarely come into direct contact with CAP messages themselves, and when they do, most of them find them complex if not downright bizarre. Most human interaction is not with CAP messages themselves, but with application-specific user interfaces. This can be a source of confusion, since non-technical users (and occasionally even technical ones) may confuse the presentation of a CAP message with the CAP message itself.

In practice a CAP-related user interface can be as simple as a push-button on the input side, or a buzzer or siren on the output. It also can be as complex as an animated three-dimensional map display or a complete hazardous materials release modeling program that outputs CAP messages.

Effective human interface design is beyond the scope of this article. The key point for our purposes here is that "the map is not the territory"... we should be careful not to confuse the human interface--which should be designed around whatever human task it supports--with the underlying interoperable data structure standard that is CAP.

CAP-based Activation of Devices

One of the most common uses of CAP is to activate digital devices, such as those used to display or distribute warnings. While there can be enormous variety in the sort of devices and systems that can be activated by CAP messages, the interfaces between the CAP messaging (transport) infrastructure and the activated device or system inevitably have three components:

1. CAP Messaging Client - Some mechanism for obtaining individual CAP messages from the infrastructure. Sometimes referred to as the "CAP client" part of the interface.
2. CAP Policy Filter - Logic that determines whether an individual CAP message is appropriate for action by the device or system served by this interface. Filter criteria may include geospatial ("Is this alert for my area?"), source ("Is this from somebody I'm supposed to listen to?"), threshold ("Is this alert above my urgency/severity/certainty thresholds for activation?") or other factors derived from the CAP message. It also may consider "extrinsic" factors such as time of day, current state of the target system, etc.
3. Device/System Actuator - Transforms any message that passes the policy filter stage into a form acceptable to the target system; e.g., a switch closure for a light or siren, a formatted text command string for a digital device, an audio output to feed radio broadcasts, etc.