ATOCA M. Lepinski Internet-Draft BBN Technologies Intended status: Informational K. Seo Expires: November 4, 2012 BBN Technologes R. Barnes BBN Technologies May 3, 2012 Alert Metadata Protocol (AMP) draft-barnes-atoca-meta-02.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 November 4, 2012. Copyright Notice Copyright (c) 2012 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 November 4, 2012 [Page 1] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 2] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 3] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 4] Internet-Draft AMP May 2012 "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 November 4, 2012 [Page 5] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 6] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 7] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 8] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 9] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 10] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 11] Internet-Draft AMP May 2012 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-03 (work in progress), March 2012. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Lepinski, et al. Expires November 4, 2012 [Page 12] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 13] Internet-Draft AMP May 2012 } # 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 November 4, 2012 [Page 14] Internet-Draft AMP May 2012 { "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 November 4, 2012 [Page 15] Internet-Draft AMP May 2012 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 November 4, 2012 [Page 16]