ATOCA M. Lepinski
Internet-Draft K.Seo
Intended status: Informational R. Barnes
Expires: May 2, 2012 BBN Technologes
October 30, 2011
Alert Metadata Protocol (AMP)
draft-barnes-atoca-meta-01.txt
Abstract
Recipients of emergency alerts need to discover information about
local alert distribution servers, and to register contact points
where they can receive alerts. This document defines a mechanism for
IP networks to advertise a local alert server, and a protocol that
devices on the network can use to retrieve local information and
register information about themselves.
Please send feedback to the atoca@ietf.org mailing list.
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 http://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 May 2, 2012.
Copyright Notice
Copyright (c) 2011 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
(http://trustee.ietf.org/license-info) in effect on the date of
Lepinski, et al. Expires May 2, 2012 [Page 1]
Internet-Draft AMP October 2011
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 Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Open Questions . . . . . . . . . . . . . . . . . . . . . . 3
2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Server Discovery . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. NAPTR Record Format . . . . . . . . . . . . . . . . . . . 4
3.2. Client Processing . . . . . . . . . . . . . . . . . . . . 5
4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Message Format . . . . . . . . . . . . . . . . . . . . . . 6
4.1.1. Registration . . . . . . . . . . . . . . . . . . . . . 6
4.1.2. Advertisement . . . . . . . . . . . . . . . . . . . . 7
4.1.3. Refer . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1.4. Alert . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2. HTTP Transport of AMP Messages . . . . . . . . . . . . . . 9
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
5.1. AMP Message Type Registry . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. JSON Schema for AMP Messages . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
Lepinski, et al. Expires May 2, 2012 [Page 2]
Internet-Draft AMP October 2011
1. Introduction
In order for clients to securely receive alerts from alert servers,
both endpoints and servers need a certain amount of configuration.
For example, clients need to know the identities of trusted alerting
authorities so that they can reject false alerts. In some
environments, servers need to gather location and contact information
for end clients to support alert targeting and delivery.
This document defines a protocol that addresses this problem in two
parts. First, a client discovers a local alert server using
information provided by its local network. Second, the client
connects to the server and conducts an exchange of alerting-related
metadata.
1.1. Open Questions
The current version of this draft specifies transport security (i.e.,
TLS) as the only mechanism for providing security for AMP messages.
However, this document could also specify as an option the use the
mechanisms defined by of the JOSE working group to provide object
security for the JSON bodies on a per-message basis (independent of
the underlying transport).
The current version of this draft specifies that Local Alert
Distribution Servers will be discovered by via a U-NAPTR query using
the domain name of the local network (in a fashion analogous to LIS
discovery in [RFC5986]). An alternative approach would be to use
standard LOST discovery [RFC5223] and then find the appropriate Local
Alert Distribution Server by making a LOST query for some newly
defined alert URN.
The current version of this draft specifies only an HTTP transport
for AMP messages. However, as an alternative this document could
also specify an option to use WebSockets as a transport for AMP
messages.
2. Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
The entities involved in this protocol are referred to as the
"client" and "server". A client is any entity that is interested in
receiving emergency alerts. A server in the sense of this document
is an entity that maintains information about clients and information
Lepinski, et al. Expires May 2, 2012 [Page 3]
Internet-Draft AMP October 2011
about how alerts are delivered within some scope (e.g., within a
jurisdiction); it may or may not be the server that actually delivers
emergency alerts.
3. Server Discovery
Since many alerting scenarios are local (e.g., natural disasters) and
ISPs are well-positioned to gather information on their local
environment, it can be useful for an ISP to provide information about
local alerting resources to clients. Likewise, clients should be
able to discover information advertised by their local networks.
The mechanism presented here is based on the discovery procedure
described in RFC 5986 [RFC5986]. It relies on the DHCP option for
Access Network Domain Name, which is specified in RFC 5986 for both
DHCPv4 and DHCPv6. IP networks that support emergency alerting
SHOULD provide the Access Network Domain Name option to devices on
network that are configured via DHCP. This option provides to the
device a domain name that is suitable for service discovery within
the access network.. This domain is used as input to the U-NAPTR
resolution process for alert server discovery.
In addition to providing the Access Network Domain Name to devices
via DHCP, an IP network that supports emergency alerting SHOULD
provision DNS records to support a U-NAPTR lookup for LADS discovery.
U-NAPTR [RFC4848] is a Dynamic Delegation Discovery Service (DDDS)
profile that produces a URI (in this case, the URI for the
appropriate AMP alert server). Section 3.1 specifies the format of
the DNS NAPTR record used for this discovery, and Section 3.2
provides processing instructions for the client device performing the
discovery.
3.1. NAPTR Record Format
U-NAPTR resolution for an alert server takes a domain name as input
and produces a URI that identifies the alert server. This process
also requires an Application Service tag and an Application Protocol
tag, which differentiate NAPTR records for alert server discovery
from other records for that domain. Section 5.1 defines an
Application Service tag of "AMP", which is used to identify the AMP
alert server that is appropriate for use by devices in a given
domain. The Application Protocol tags "http", "https", "ws", and
"wss" are used to identify alert servers that support these
protocols. The NAPTR records in the following example demonstrate
the use of the Application Service and Protocol tags. Iterative
NAPTR resolution is used to delegate responsibility for the alert
server from "zonea.example.net." and "zoneb.example.net." to
Lepinski, et al. Expires May 2, 2012 [Page 4]
Internet-Draft AMP October 2011
"outsource.example.com."
zonea.example.net.
;; order pref flags
IN NAPTR 100 10 "" "AMP:http" ( ; service
"" ; regex
outsource.example.com. ; replacement
)
zoneb.example.net.
;; order pref flags
IN NAPTR 100 10 "" "AMP:http" ( ; service
"" ; regex
outsource.example.com. ; replacement
)
outsource.example.com.
;; order pref flags
IN NAPTR 100 10 "u" "AMP:http" ( ; service
"!.*!wss://alerts.example.org:80/!" ; regex
. ; replacement
)
Figure 1: Sample AMP NAPTR Records
U-NAPTR resolution might produce multiple results from each iteration
of the algorithm. Order and preference values in the NAPTR record
determine which value is chosen. A Device MAY attempt to use
alternative choices if the first choice is not successful. An HTTPS
or WSS URI for an alert server that is a product of U-NAPTR MUST be
authenticated using the domain name method described in Section 3.1
of RFC 2818 [RFC2818]. The domain name that is used in this
authentication is the one extracted from the URI, not the one that
was input to the U-NAPTR resolution process.
3.2. Client Processing
In order to discover an appropriate alert server, a client device
must first obtain a domain name for the local access network. The
client device first attempts to obtain configuration information via
DHCP. If the DHCP configuration contains the Access Network Domain
Name option, then the client uses the domain name in this option as
the domain name for the local access network. Once the client has
the domain name of the local access network, it uses this domain name
to make a U-NAPTR query [RFC4848] for the Application Service AMP in
this domain.
If the DHCP configuration does not contain the Access Network Domain
Name option, then the client should look up its own IP address in the
reverse DNS to obtain a domain name. The client should then attempt
Lepinski, et al. Expires May 2, 2012 [Page 5]
Internet-Draft AMP October 2011
to use this domain name as the domain name for the local access
network. Note that if the U-NAPTR query using this domain name
fails, then the client device should iteratively repeat the U-NAPTR
query using as the domain name of the local access network the domain
name obtained by removing the left-most portion of the domain name
used in the previous attempt.
4. Protocol
The Alert Metadata Protocol (AMP) consists of a set of messages
encoded as JSON objects [RFC4627]. Section 4.1 describes the four
messages for the AMP protocol, Registration, Advertisement, Refer,
and Alert. The complete JSON schema for these four message types
appears in Appendix A. Section 4.2 specifies the use of HTTP as a
transport for AMP messages. A MIME Type, application/amp+json, for
use with AMP messages is registered in Section 5.
[Author's Note: Future versions of this document may define other
transports AMP messages, e.g., WebSockets]
4.1. Message Format
Each AMP message is a JSON object consisting of a "type" and an array
of "fields" that depend on the message type. Each of the four
message types, Registration, Advertisement, Refer, and Alert, are
described along with their corresponding properties in the following
subsections. (A complete JSON scheme for these four message types
appears in Appendix A.) Future documents may define additional
message types. Therefore, implementations MUST ignore any AMP
message containing a type field that it does not recognize.
4.1.1. Registration
Registration messages are sent from clients to servers. They are
used by the clients to register with a server in order to receive
future alerts of the proper type and format (e.g., language). The
same message is also used to update existing registration information
or to request deletion of existing registration information. Note
that for location information, the Registration makes use of the
PIDF-LO format, which is defined in [RFC4119]. Registration messages
contain the following fields:
token This field is a string that identifies the client. This field
is optional and does not appear in the first registration message
sent by a client to a particular server. However, once a client
has received an advertisement message from a server, it copies the
token from that message into all future registration messages so
Lepinski, et al. Expires May 2, 2012 [Page 6]
Internet-Draft AMP October 2011
that the server can distinguish between new registrations and
updates to existing registrations.
contacts This field is an array of strings, where each string
contains a URI that can be used contact the client. This field is
optional. If this field is not included then the registration is
interpreted by the server as a request to delete existing
registration information for this client.
location This field is a string containing a "location-info" element
from a PIDF-LO. This field is optional, but it must be present if
the contacts field is present.
language This field is a string containing the language in which the
client wishes to receive alerts. This field uses the same values
as the HTTP language tag. This field is optional, but it must be
present if the contacts field is present.
If a server receives a new registration message from a previously
registered client (i.e., a registration message containing a token
that the server has previously sent in an advertisement message),
then the server should replace the existing registration information
for that client with the information contained in the new
registration message. If the server receives a registration message
containing only the token field, then the server should delete any
existing registration information associated with this client.
4.1.2. Advertisement
Advertisement messages are sent from servers to clients. These
messages allow servers to notify clients about local alert
authorities that sign authoritative alerts. This enables the client
to validate future alerts regardless of the protocol mechanism used
to transport the alert. An advertisement message contains the
following fields:
token This field is a string that identifies the client. This field
is mandatory. The server selects a token for the client when it
first receives a registration from that client. The server then
includes the token in all advertisement messages sent to that
client.
contacts This field is an array of strings, where each string
contains a URI from which local alerts may be sourced. This field
is mandatory and the array MUST NOT be empty.
Lepinski, et al. Expires May 2, 2012 [Page 7]
Internet-Draft AMP October 2011
certs This field is an array of strings, where each string contains
an X.509 certificate for a local authority. These certificates
are used to validate local alerts signed by the given authority.
This field is optional, but either this field or the public_keys
field MUST be present and not empty.
public_keys This field is an array of strings, where each string
contains Subject Public Key Information (SPKI) for a local
authority. These are the public keys used to validate alerts
signed by the given authority. This field is optional, but either
this field or the public_keys field MUST be present and not empty.
hash_values This field is an array of hash values that are used in
ESCAPE verification. This field is mandatory and the array MUST
NOT be empty.
ttl: This field is a positive integer that indicates the length of
time (in seconds) for which this advertisement is valid. If the
client does not receive a new advertisement message from the
server before the ttl indicates that the advertisement is stale,
then the client should attempt to obtain a new advertisement
message by sending a registration message to the server.
4.1.3. Refer
Advertisement messages are sent from servers to clients. These
messages allow servers to notify clients of a different AMP server
that the client should contact. For example, if an AMP server
receives a registration message indicating a location outside its
jurisdiction, it might send a refer message that refers the client to
an appropriate server for the client's current location. A refer
message must contain the following fields:
to This field is a string that contains the URI of the AMP server to
which the client is being referred.
Upon receiving a Refer message, a client SHOULD send a new
registration message to the AMP server indicated in the "to" field of
the refer message.
4.1.4. Alert
Alert messages are sent from servers to client. These messages are
one mechanism for distributing local alerts. (Other mechanisms for
transporting local alerts include LEAP [I-D.barnes-atoca-delivery].)
Alerts sent using an AMP alert message are ESCAPE-encoded
[I-D.barnes-atoca-escape]. An alert message contains the following
fields:
Lepinski, et al. Expires May 2, 2012 [Page 8]
Internet-Draft AMP October 2011
alert_data This field is a string that contains an ESCAPE-encoded
alert message.
The procedure for validating ESCAPE-encoded alert messages can be
found in [I-D.barnes-atoca-escape]
4.2. HTTP Transport of AMP Messages
This section describes the use of HTTP [RFC2616] and HTTP over TLS
[RFC2818] as transport mechanisms for the AMP protocol, which a
conforming alert server and client MUST support.
Although AMP uses HTTP as a transport, it uses a strict subset of
HTTP features, and due to the restrictions of some features, an alert
server is not a fully compliant HTTP server. It is intended that an
alert server can easily be built using an HTTP server with
extensibility mechanisms and that an AMP client can trivially use
existing HTTP libraries. This subset of requirements helps
implementors avoid ambiguity with the many options that the full HTTP
protocol offers.
A client that conforms to this specification MAY choose not to
support HTTP authentication [RFC2617] or cookies [RFC2965]. Because
the client and the alert server may not necessarily have a prior
relationship, the alert server SHOULD NOT require a client to
authenticate, either using the above HTTP authentication methods or
TLS client authentication. Unless all clients that access a LIS can
be expected to be able to authenticate in a certain fashion, denying
access to alerts could prevent a client from receiving critical
emergency information.
An AMP Registration message MUST be carried in the body of an HTTP
POST request. The client MUST include a Host header in the request.
The alert server response to a registration request MUST be 200
unless there is an HTTP-layer error. The Response SHOULD contain an
AMP Advertisement message. The POST method is the only method
REQUIRED for AMP.
The MIME type of an AMP registration request and response bodies is
"application/amp+json". The alert server and the client MUST provide
this value in the HTTP Content-Type and Accept header fields. If the
alert server does not receive the appropriate Content-Type and Accept
header fields, the alert server SHOULD fail the request, returning a
406 (not acceptable) response. AMP responses SHOULD include a
Content-Length header.
Clients MUST NOT use the "Expect" header or the "Range" header in AMP
requests. The alert server MAY return 501 (not implemented) errors
Lepinski, et al. Expires May 2, 2012 [Page 9]
Internet-Draft AMP October 2011
if either of these HTTP features are used. In the case that the
alert server receives a registration request from the client
containing an If-* (conditional) header, the alert server SHOULD
return a 412 (precondition failed) response.
The alert server populates the HTTP headers of responses so that they
are consistent with the contents of the message. In particular, the
"Cache-Control" header SHOULD be set to disable caching of AMP
Advertisement messages by HTTP intermediaries. Instead, the alert
server controls caching of AMP Advertisement messages by setting the
TTL field in the Advertisement message.
The alert server SHOULD NOT use an HTTP 3xx response to redirect an
AMP Registration request. Instead, the alert server SHOULD redirect
AMP Registration requests by providing an HTTP 200 response
containing the AMP Refer message.
Implementations of AMP that implement HTTP transport MUST implement
transport over TLS [RFC2818]. TLS provides message integrity and
confidentiality between the client and alert server. The client MUST
implement the server authentication method described in Section 3.1
of [RFC2818], with an exception in how wild cards are handled. The
leftmost label MAY contain the wild card string "*", which matches
any single domain name label. Additional characters in this leftmost
label are invalid (that is, "f*.example.com" is not a valid name and
does not match any domain name). The client uses the URI obtained
during alert server discovery to authenticate the server. The
details of this authentication method are provided in Section 3.1 of
HTTPS [RFC2818]. When TLS is used, the client SHOULD fail a request
if server authentication fails, except in the event of an emergency.
5. IANA Considerations
This document requires several registrations by IANA into existing
registries, and creates a new registry of AMP message codes.
[[ TODO: Register NAPTR service tag "AMP" and application protocols
"http", "https" ]]
[[ TODO: Register media type application/amp+json ]]
5.1. AMP Message Type Registry
IANA is requested to create a new registry of AMP Message Types.
This registry contains two fields, the name of the name of the
registered message type, and a specification pointer containing a
reference to the document that defines the registered message type.
Lepinski, et al. Expires May 2, 2012 [Page 10]
Internet-Draft AMP October 2011
IANA is requested to populate this new registry with the following
four entries:
Message Type Name Specification Pointer
+--------------------------------+--------------------------------+
| Registration | draft-barnes-atoca-meta |
| Advertisement | draft-barnes-atoca-meta |
| Refer | draft-barnes-atoca-meta |
| Alert | draft-barnes-atoca-meta |
+--------------------------------+--------------------------------+
6. Security Considerations
[Author's Note: The Security Considerations will be fleshed out in
more detail in the next version of this document.]
The AMP protocol contains contact and location information for a
device which for many devices will consist of private information
regarding the user of the device. Therefore, confidentiality
protection should be used when the registration request contains
private information.
The modification of AMP messages can cause client devices to accept
false alerts (in the case where the advertisement is modified) or to
receive alerts for the improper location (if the registration is
modified). Therefore, integrity protection should be applied to AMP
messages.
The AMP protocol runs over HTTP. Therefore, the use of HTTP over TLS
can provide confidentiality and integrity protection for AMP
messages.
Alert server discovery makes use of NAPTR. Standard security
considerations involving the use of NAPTR apply. DNSSEC SHOULD be
used to protect the DNS responses provided during the discovery
procedure.
7. Acknowledgements
The authors would like to thank Derrick Kong for help in creating the
JSON schema for the AMP protocol.
8. References
Lepinski, et al. Expires May 2, 2012 [Page 11]
Internet-Draft AMP October 2011
8.1. Normative References
[I-D.barnes-atoca-escape]
Barnes, R., "Encoding of Secure Common Alert Protocol
Entities (ESCAPE)", draft-barnes-atoca-escape-00 (work in
progress), October 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC4119] Peterson, J., "A Presence-based GEOPRIV Location Object
Format", RFC 4119, December 2005.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4848] Daigle, L., "Domain-Based Application Service Location
Using URIs and the Dynamic Delegation Discovery Service
(DDDS)", RFC 4848, April 2007.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009.
[RFC5986] Thomson, M. and J. Winterbottom, "Discovering the Local
Location Information Server (LIS)", RFC 5986,
September 2010.
8.2. Informative References
[I-D.barnes-atoca-delivery]
Barnes, R., "Lightweight Emergency Alerting Protocol
(LEAP)", draft-barnes-atoca-delivery-01 (work in
progress), October 2011.
[I-D.ietf-atoca-requirements]
Schulzrinne, H., Norreys, S., Rosen, B., and H.
Tschofenig, "Requirements, Terminology and Framework for
Exigent Communications", draft-ietf-atoca-requirements-02
(work in progress), October 2011.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP
Lepinski, et al. Expires May 2, 2012 [Page 12]
Internet-Draft AMP October 2011
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[RFC2965] Kristol, D. and L. Montulli, "HTTP State Management
Mechanism", RFC 2965, October 2000.
[RFC5223] Schulzrinne, H., Polk, J., and H. Tschofenig, "Discovering
Location-to-Service Translation (LoST) Servers Using the
Dynamic Host Configuration Protocol (DHCP)", RFC 5223,
August 2008.
Appendix A. JSON Schema for AMP Messages
# Registration
{
"type":"Registration",
"fields":
{
"token":
{
"type":"string",
"description":"Identifier for client",
"required":false
},
"contacts":
{
"description":"Array of URIs",
"type":"array",
"uri":
{
"type":"string"
}
"required":false
},
"location":
{
"type":"string",
"description":"Location-info element from PIDF-LO",
"required":false
},
"language":
{
"type":"string",
"description":"Language tag",
"required":false
},
}
Lepinski, et al. Expires May 2, 2012 [Page 13]
Internet-Draft AMP October 2011
}
# Advertisement
{
"type":"Advertisement",
"fields":
{
"contacts":
{
"description":"Array of source URIs for alerts sourced",
"type":"array",
"uri":
{
"type":"string"
}
"required":true
},
"token":
{
"type":"string",
"description":"Identifier that client should use in future",
"required":true
},
"certs":
{
"description":"Array of certificates for local authorities",
"type":"array",
"cert":
{
"type":"string"
}
"required":false
},
"public_keys":
{
"description":"Array of SPKIs for local authorities",
"type":"array",
"spki":
{
"type":"string"
}
"required":false
},
"hash_values":
{
"description":"Array of hash values for ESCAPE verification",
"type":"array",
"hash":
Lepinski, et al. Expires May 2, 2012 [Page 14]
Internet-Draft AMP October 2011
{
"type":"string"
}
"required":true
},
"ttl":
{
"type":"number",
"description":"Number of seconds for advertisement validity",
"required":true
}
}
}
# Refer
{
"type":"Refer",
"fields":
{
"to":
{
"type":"string",
"description":"URI of new AMP server client should contact",
"required":true
}
}
}
# Alert
{
"type":"Alert",
"fields":
{
"alert_data":
{
"type":"string",
"description":"ESCAPE-encoded alert data",
"required":true
}
}
}
Lepinski, et al. Expires May 2, 2012 [Page 15]
Internet-Draft AMP October 2011
Authors' Addresses
Matt Lepinski
BBN Technologies
10 Moulton St
Cambridge, MA 02138
US
Phone: +1 617 873 5939
Email: mlepinski@bbn.com
Karen Seo
BBN Technologes
10 Moulton St
Cambridge, MA 02138
US
Phone: +1 617 873 3152
Email: kseo@bbn.com
Richard Barnes
BBN Technologies
9861 Broken Land Parkway
Columbia, MD 21046
US
Phone: +1 410 290 6169
Email: rbarnes@bbn.com
Lepinski, et al. Expires May 2, 2012 [Page 16]