GEOPRIV K. Doran Internet-Draft R. Barnes Intended status: Informational BBN Technologies Expires: September 10, 2010 March 9, 2010 A Common Framework for Location Protocols draft-doran-geopriv-proto-map-01 Abstract There are currently several protocols developed by different standards organizations that implement a basic design pattern where a client requests location from a location server and the server responds with location information. This document defines the Common Location Interoperability Framework (CLIF), a general data model for such protocols, and describes how some existing geolocation protocols can be mapped into this unified model. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 10, 2010. Copyright Notice Copyright (c) 2010 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 Doran & Barnes Expires September 10, 2010 [Page 1] Internet-Draft CLIF March 2010 Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of 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 BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 5 4. Request parameters . . . . . . . . . . . . . . . . . . . . . . 6 4.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.1.1. Callback . . . . . . . . . . . . . . . . . . . . . . . 6 4.1.2. Language . . . . . . . . . . . . . . . . . . . . . . . 6 4.1.3. Response Accuracy . . . . . . . . . . . . . . . . . . 7 4.1.4. Response Age . . . . . . . . . . . . . . . . . . . . . 7 4.1.5. Response Time . . . . . . . . . . . . . . . . . . . . 7 4.1.6. Response Location Type . . . . . . . . . . . . . . . . 7 4.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 8 4.2.1. Unique Identifier (UID) . . . . . . . . . . . . . . . 9 4.2.2. Network Access Identifier (NAI) . . . . . . . . . . . 9 4.2.3. Network Access Password . . . . . . . . . . . . . . . 9 4.2.4. Group Identifier . . . . . . . . . . . . . . . . . . . 9 4.2.5. IP Address . . . . . . . . . . . . . . . . . . . . . . 9 4.2.6. MAC Address . . . . . . . . . . . . . . . . . . . . . 10 4.2.7. Port Number . . . . . . . . . . . . . . . . . . . . . 10 4.2.8. URI . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2.9. Fully Qualified Domain Name . . . . . . . . . . . . . 10 4.2.10. Telephony . . . . . . . . . . . . . . . . . . . . . . 10 4.2.10.1. Mobile Station International Subscriber Dial Number (MSISDN) . . . . . . . . . . . . . . . . . 11 4.2.10.2. International Mobile Subscriber Identity (IMSI) . . . . . . . . . . . . . . . . . . . . . 11 4.2.10.3. International Mobile Equipment Identifier (IMEI) . . . . . . . . . . . . . . . . . . . . . 11 4.2.10.4. Mobile Identification Number (MIN) . . . . . . . 11 4.2.10.5. Mobile Directory Number (MDN) . . . . . . . . . . 11 4.2.10.6. Home Mobile Country Code . . . . . . . . . . . . 11 4.2.10.7. Home Mobile Network Code . . . . . . . . . . . . 12 4.3. Measurement . . . . . . . . . . . . . . . . . . . . . . . 12 4.3.1. Timestamp . . . . . . . . . . . . . . . . . . . . . . 12 4.3.2. Expires . . . . . . . . . . . . . . . . . . . . . . . 12 4.3.3. Samples . . . . . . . . . . . . . . . . . . . . . . . 12 Doran & Barnes Expires September 10, 2010 [Page 2] Internet-Draft CLIF March 2010 4.3.4. WifiMeasurement . . . . . . . . . . . . . . . . . . . 12 4.3.4.1. NIC Type . . . . . . . . . . . . . . . . . . . . 13 4.3.4.2. Wireless Access Point (WAP) . . . . . . . . . . . 13 4.3.5. CellularMeasurement . . . . . . . . . . . . . . . . . 15 4.3.5.1. Radio Type . . . . . . . . . . . . . . . . . . . 15 4.3.5.2. Carrier . . . . . . . . . . . . . . . . . . . . . 15 4.3.5.3. Cellular Tower . . . . . . . . . . . . . . . . . 15 4.3.6. WiMAX . . . . . . . . . . . . . . . . . . . . . . . . 17 4.3.7. GNSS . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.3.8. w16e . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.4. Other parameters . . . . . . . . . . . . . . . . . . . . . 17 5. Response parameters . . . . . . . . . . . . . . . . . . . . . 17 5.1. General parameters . . . . . . . . . . . . . . . . . . . . 17 5.1.1. Message . . . . . . . . . . . . . . . . . . . . . . . 17 5.1.2. Age . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.1.3. Unique Identifer (UID) . . . . . . . . . . . . . . . . 18 5.2. Location Reference . . . . . . . . . . . . . . . . . . . . 18 5.3. Location Oject [PIDF-LO] . . . . . . . . . . . . . . . . . 18 5.3.1. Geodetic location . . . . . . . . . . . . . . . . . . 18 5.3.2. Civic location . . . . . . . . . . . . . . . . . . . . 18 5.4. Error . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.4.1. Error Code . . . . . . . . . . . . . . . . . . . . . . 18 5.4.2. Error Message . . . . . . . . . . . . . . . . . . . . 19 6. Protocol mapping summary . . . . . . . . . . . . . . . . . . . 19 6.1. HELD . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 6.1.1. Location Request Message . . . . . . . . . . . . . . . 23 6.1.2. Location Response Message . . . . . . . . . . . . . . 23 6.1.3. Error Message . . . . . . . . . . . . . . . . . . . . 23 6.2. Google Gears . . . . . . . . . . . . . . . . . . . . . . . 23 6.2.1. Location Request Message . . . . . . . . . . . . . . . 26 6.2.2. Location Response Message . . . . . . . . . . . . . . 29 6.3. Parlay/X . . . . . . . . . . . . . . . . . . . . . . . . . 29 6.3.1. getLocation Request Message . . . . . . . . . . . . . 31 6.3.2. getLocation Response Message . . . . . . . . . . . . . 31 6.3.3. getLocationForGroup Request Message . . . . . . . . . 31 6.3.4. getLocationForGroup Response Message . . . . . . . . . 31 7. Applications . . . . . . . . . . . . . . . . . . . . . . . . . 31 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 32 9. Security Considerations . . . . . . . . . . . . . . . . . . . 32 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10.1. Normative References . . . . . . . . . . . . . . . . . . . 32 10.2. Informative References . . . . . . . . . . . . . . . . . . 33 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 Doran & Barnes Expires September 10, 2010 [Page 3] Internet-Draft CLIF March 2010 1. Introduction Over time, the increasing mobility of Internet endpoints, and the global basis on which Internet applciations are delivered, have driven demand for geolocation information about Internet hosts. In order to respond to the demand, many different organizations have developed geolocation platforms and protocols. For example, the SUPL and MLP location protocols for cellular networks were developed in the 3GPP and OMA, while the Parlay/X location protocol for tradional fixed-line telephone networks was developed in ETSI. While many of these protocols have matured idependently, because they are similiar in purpose, the data models that they define are also similiar. While the terminoligy for data elements may vary, the definitions are often analogous, if not equivalent. Despite the clear overlap of function, different protocols continue to be used independently, perpetuating a fragmented marketplace for location services. This fragmentation did not cause problems while the domains of different protocols remained distinct. However, many different types of networks, with their own "native" location protocols, are now being used to carry IP traffic. At the same time, geolocation functiosn are being introduced as core components of modern web browsers and operating systems. These trends argue for a unification of the current space of location protocols in order to facilitate location services that are interoperable across the entire Internet. Obviously, a proliferation of protocols has practical implications as well. Without a single universal data model, developers are forced to choose which protocols to use or support in their implemetations. Server and client components have little re-usability and interoperability across protocols. Transitioning from one protocol to another is expensive and difficult. This is an unfortunate situation, espescially because it could be avoided given the similarities among protocols. In fact, if a universal data model is agreed upon, and the process for mapping various protocols to and from that data model is standardized, these problems can be resolved. This document introduces a universal geolocation data model that will meet the needs of the majority of exisiting protocols and be extensible to accomodate future protocols. We call this universal data model the Common Location Interoperability Framework, or CLIF. This document also provides mappings of some exisiting geolocation protocols to this data model. A main goal of these mappings is to reduce confusion resulting from the use of different terminology to mean the same thing in different specifications. Doran & Barnes Expires September 10, 2010 [Page 4] Internet-Draft CLIF March 2010 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 [1]. 3. Data Model Overview CLIF has two top level message types: Request and Response. In both 'pull'- and 'push'-style systems, there is an entity that wants to know location (requester or client) and an entity that provides location (responder or server). The request object represents the messages that originate from requesters, and likewise, the response object represents messages originating from responders. These two general message types satistfy the needs of many current location location protocols. Protocols that use a request/response message flow -- especially those that use HTTP as a transport -- are of course naturally suited to this model, for example: o HELD [ref:draft-ietf-geopriv-http-location-delivery] o MLP [ref] o Parlay/X [ref] (when used with "get"-style requests) o Google Gears [ref] . The data model also fits into protocols that use a subscribe/ notify pattern, since such protocols can be thought of as a request (subscription) followed by multiple responses (notifications): o Parlay/X [ref] (when used with "notification"-style requests) o LOCSIP [ref] o SIMPLE [ref:RFC4079] Geolocation platforms that depend on client-originated location updates can also use this data model, e.g., to provide rough location as an input to location determination. So this request/response structured data model is flexible enough to fit into many different types of protocols and message flows. The request object contains any information that is necessary or helpful for a location provider in determining the target's location. This information includes, for example, identifiers for the target, Doran & Barnes Expires September 10, 2010 [Page 5] Internet-Draft CLIF March 2010 signal measurements, constraints on the response, callback URIs. The response object contains location objects or error information (or possibly both). In addition raw location information, a location object typically contains an identifier for the target, a timestamp, and possibly privacy rules. A response object does not necessarily have to be used as a "response" in the underlying transport protocol (e.g., in HTTP or SIP). Responses can be used by any entity that wants to send a location object to another, e.g., a server sending an unsolicited update to a client (as in a DHCP announcement). 4. Request parameters This section defines a CLIF request object. 4.1. General Parameters listed under "General" are top level parameters not falling under any particular categorization. 4.1.1. Callback Field name: callback Data type: string (URI) The "callback" parameter specifies a callback address to which the location response should be sent. The value of this paramter is a URI. In the case of a third-party location query, this field is used to specify the address of the first-party device that is performing the lookup on behalf of the third-party device. 4.1.2. Language Field name: language Data type: string Value Space: two-character and three-character codes as specified in ISO 639 The "language" parameter specifies a requested langauge for a response containing a civic address. Language values should follow two-character and three-character representations defined in [ISO639]. Doran & Barnes Expires September 10, 2010 [Page 6] Internet-Draft CLIF March 2010 4.1.3. Response Accuracy Field name: accuracy Data type: int / double ? Units: meters? The "accuracy" parameter specifies the requested accuracy for a response containing a geodetic address. 4.1.4. Response Age Field name: maxAge Data type: string (date-time) The "maxAge" parameter defines the maximum age of the location in the response. [How should tolerance of this request parameter be handled if it cannot be satisfied? Let each implementation define it? Add tolerance parameters?] 4.1.5. Response Time Field name: responseTime Data type: ? The "responseTime" parameter defines the requested maximum response time for the location provider to respond to the location request. [How should this be represented?] 4.1.6. Response Location Type Field name: locationType Data type: byte Format: Combination of bitmap flags according to table below: Doran & Barnes Expires September 10, 2010 [Page 7] Internet-Draft CLIF March 2010 +------+--------------------------------------+ | Flag | Location Type | +------+--------------------------------------+ | ---1 | Geodetic Location Type Flag | | --1- | Civic Location Type Flag | | -1-- | Reference Location Type Flag | | 1--- | Exact Modifier Flag | | 1000 | Default Location Type (special case) | +------+--------------------------------------+ Table 1 These flags can be combined in any way. For example "-111" would ask for all location types, while "-011" would ask for Geodetic and Civic location types. Specifying no location types ("0000") is the equivalent of asking for any available location type(s). The "exact" modifier is used to specify how the location provider should handle the other flags. Specifically, if the exact modifier is set to 0 (false), then the location provider MUST provide the requested location types in the response, but it MAY provide more. If the exact modifier is set to 1 (true), the location provider MUST provide exactly the types requested, no more or less, and it MUST return an error if it cannot satisfy the request. There is one special cases, indicated by "1000". If the location provider sees this flag comination, it should simply follow its default behavior. Note that this is slightly different from "0000," which asks the locaiton provider to return any location type. For example if a location provider's default behavior is to return geodetic location only, then the "1000" flag would return a geodetic location, whereas the "0000" flag might return both geodetic and civic locations. 4.2. Identifiers Identifiers are parameters that identify the device that is requesting location. For third-party location queries, these should describe the third-party device, not the first-party requester. That is, if Device A requesting location on behalf of Device B, identifiers should describe Device B, and Device A can be specified via the "callback" parameter. A Location Request object can store more that one Identifiers objects for cases where it is requesting the location of multiple entities from the same location provider in a single request. Doran & Barnes Expires September 10, 2010 [Page 8] Internet-Draft CLIF March 2010 4.2.1. Unique Identifier (UID) Field name: uid Data type: string The "uid" parameter MAY be used to define any Unique Identifier applicable to the protocol being represented, e.g., "DUID" for location over DHCP. A "uid" should not be confused with a network access identifier (see NAI below). 4.2.2. Network Access Identifier (NAI) Field name: accessUsername Data type: string To be used with protocols that require authentication ie, username, user@domain (See [RFC4282] for full definition) 4.2.3. Network Access Password Field name: accessPassword Data type: string Password associated with UNI for networks that require username/ password authentication 4.2.4. Group Identifier Field name: groupId Data type: string Format: any The "group" parameter MAY be used to define a group/buddy list when looking up a location for multiple users. This is used for third- party requests. 4.2.5. IP Address Field name: ip Data type: string Doran & Barnes Expires September 10, 2010 [Page 9] Internet-Draft CLIF March 2010 The "ip" parameter stores IP address of the requester. 4.2.6. MAC Address Field name: mac Data type: string The "mac" parameter stores the MAC address (bssid) of the requester. 4.2.7. Port Number Field name: port Data type: int The "port" parameter MAY be used to specify the UDP or TCP Port being used. This is useful for mulitple requesters running on same IP on different ports. 4.2.8. URI Field name: uri Data type: string (URI) A "uri" parameter can specify a uri that identifies the requester. 4.2.9. Fully Qualified Domain Name Field name: fqdn Data type: string The fully qualified domain name of the requester can be stored in the "fqdn" parameter. This should be a domain name that resolves to a single device. ie, server-1.example.com. 4.2.10. Telephony Data type: Telephony Object The Telephony object contains fields to store various telephony identifiers. Doran & Barnes Expires September 10, 2010 [Page 10] Internet-Draft CLIF March 2010 4.2.10.1. Mobile Station International Subscriber Dial Number (MSISDN) Field name: msidn Data type: string Mobile Station International Subscriber Dial Number (MSISDN) 4.2.10.2. International Mobile Subscriber Identity (IMSI) Field name: imsi Data type: string International Mobile Subscriber Identity (IMSI) - GSM / UMTS mobile subscriber identifier 4.2.10.3. International Mobile Equipment Identifier (IMEI) Field name: imei Data type: string International Mobile Equipment Identifier (IMEI) 4.2.10.4. Mobile Identification Number (MIN) Field name: min Data type: string Mobile Identification Number (MIN) - a unique number associated with CDMA devices 4.2.10.5. Mobile Directory Number (MDN) Field name: mdn Data type: string Mobile Directory Number (MDN) - usage similar to MSISDN 4.2.10.6. Home Mobile Country Code Field name: hmcc Data type: string Doran & Barnes Expires September 10, 2010 [Page 11] Internet-Draft CLIF March 2010 Mobile country code for the device's home network. 4.2.10.7. Home Mobile Network Code Field name: hmnc Data type: string Mobile network code for the device's home network. Used in conjunction with home mcc. 4.3. Measurement Data type: Object The Measurement object contains fields to store various measurements from the device. A request can have multiple Measurement objects. Every type of Measurement object has a few parameters in common, which objects that extend Measurement inherit: 4.3.1. Timestamp Field name: timestamp Data type: string The time the measurement was recorded. 4.3.2. Expires Field name: expires Data type: string The time the measurement expires. 4.3.3. Samples Field name: samples Data type: int The total number of samples on which the measurement is based. 4.3.4. WifiMeasurement Field name: WifiMeasurement Doran & Barnes Expires September 10, 2010 [Page 12] Internet-Draft CLIF March 2010 Data type: Object extends Measurement Type of Measurement object for storing WiFi Data. 4.3.4.1. NIC Type Field name: nicType Data type: string Identifies the NIC used for capturing the wifi measurements. 4.3.4.2. Wireless Access Point (WAP) Field name: Wap Data type: Object A WifiMeasurement object was a Wap object as a parameter. A Wap object describes signals from a wap the NIC sees. 4.3.4.2.1. SSID Field name: ssid Data type: string The ssid the wap is broadcasting. 4.3.4.2.2. BSSID Field name: bssid Data type: string The bssid (MAC address) of the wap. 4.3.4.2.3. Access Point Name Field name: apName Data type: string The name of the wap. Doran & Barnes Expires September 10, 2010 [Page 13] Internet-Draft CLIF March 2010 4.3.4.2.4. WAP Location Field name: location Data type: gml The location of the wap. 4.3.4.2.5. Type Field name: type Data type: enum{a|b|g|n} The type of wifi signal the wap. 4.3.4.2.6. Channel Field name: channel Data type: int The channel the wap is broadcasting on. 4.3.4.2.7. RSSI Field name: rssi Data type: int Units: dBm The radio signal strength indicator. 4.3.4.2.8. Signal to Noise Ratio Field name: snr Data type: double? Units: dBm The signal to noise ratio of the signal being broadcast by the wap. 4.3.4.2.9. Round Trip Time Field name: rtt Doran & Barnes Expires September 10, 2010 [Page 14] Internet-Draft CLIF March 2010 Data type: int? Units: milliseconds? From section-4.4 of [draft-thomson-geopriv-held-measurements-05]: "The The total round trip time from the time that a request is sent by the device to the time that it receives the response from the access point." 4.3.5. CellularMeasurement Field name: CellularMeasurement Data type: Object extends Measurement Type of Measurement object for storing Cellular Data. 4.3.5.1. Radio Type Field name: radioType Data type: string (possibly enum? e.g., gsm, cdma, wcdma, etc) Identifies the cellular radio type. 4.3.5.2. Carrier Field name: carrier Data type: string Identifies the cellular carrier by name. 4.3.5.3. Cellular Tower Field name: Tower Data type: Object A CellularMeasurement object was a Tower object as a parameter. A Tower object describes signals from a tower the cellular radio sees. 4.3.5.3.1. Mobile Country Code Field name: mcc Data type: int Doran & Barnes Expires September 10, 2010 [Page 15] Internet-Draft CLIF March 2010 4.3.5.3.2. Mobile Network Code Field name: mnc Data type: int 4.3.5.3.3. Cell Id Field name: cid Data type: int 4.3.5.3.4. 28-bit Cell Id Field name: eucid Data type: int 4.3.5.3.5. Radio Network Controller Field name: rnc Data type: int 4.3.5.3.6. Network Id Field name: nid Data type: int 4.3.5.3.7. System Id Field name: sid Data type: int 4.3.5.3.8. Base Station Id Field name: baseid Data type: int 4.3.5.3.9. RSSI Field name: rssi Data type: int Doran & Barnes Expires September 10, 2010 [Page 16] Internet-Draft CLIF March 2010 Units: dBm The radio signal strength indicator. 4.3.5.3.10. Timing Advance Field name: timingAdvance Data type: int Units: ms 4.3.6. WiMAX Measurement object for storing WiMAX Data 4.3.7. GNSS Measurement object for storing GNSS Data 4.3.8. w16e Measurement object for storing w16e Data 4.4. Other parameters Describe how CLIF can be extended here. 5. Response parameters This section defines a CLIF response object. 5.1. General parameters Parameters listed under "General" are top level parameters not falling under any particular categorization. 5.1.1. Message Field name: message Data type: string The "message" field contains any relavant report / status messages from the location provider. Doran & Barnes Expires September 10, 2010 [Page 17] Internet-Draft CLIF March 2010 5.1.2. Age Field name: age Data type: string The date-time the location was discovered. 5.1.3. Unique Identifer (UID) Field name: age Data type: string The "uid" field in the response object can store a unique identifier or access token assigned by the location provider for the requester to use for future queries. 5.2. Location Reference Field name: uri Data type: string (URI) The "uri" field in the response object can store a reference to a location. A response may have multiple Location References in an array. 5.3. Location Oject [PIDF-LO] The Location object is based on PIDF-LO. 5.3.1. Geodetic location 5.3.2. Civic location 5.4. Error Error Parameters: 5.4.1. Error Code Field name: code Data type: string The "code" field stores an error code from the location provider. Doran & Barnes Expires September 10, 2010 [Page 18] Internet-Draft CLIF March 2010 5.4.2. Error Message Field name: message Data type: string The "message" field stores an error message from the location provider. This field SHOULD be human readable text. 6. Protocol mapping summary This section provides mapping between Geolocation Protocols and CLIF. This table shows how protocols share elements with CLIF: +-----------------------------------------+------+-------+----------+ | CLIF Request | HELD | Gears | Parlay/X | +-----------------------------------------+------+-------+----------+ | callback | | | o | | language | | o | | | accuracy | | | o | | maxAge | | | o | | responseTime | | | o | | locationType | o | o | | | Identifiers:uid | o | o | o | | Identifiers:accessUsername | o | | | | Identifiers:accessPassword | | | | | Identifiers:ip | o | | | | Identifiers:mac | o | | | | Identifiers:port | o | | | | Identifiers:uri | o | | o | | Identifiers:fqdn | o | | | | Identifiers:Telephony | | | | | Identifiers:Telephony:msisdn | o | | | | Identifiers:Telephony:imsi | o | | | | Identifiers:Telephony:imei | o | | | | Identifiers:Telephony:min | o | | | | Identifiers:Telephony:mdn | o | | | | Identifiers:Telephony:hmcc | | o | | | Identifiers:Telephony:hmnc | | o | | | Measurement | | | | | Measurement:time | | o | | | Measurement:expires | | | | | Measurement:samples | | | | | WifiMeasurement::Measurement | o | o | | | WifiMeasurement:nicType | o | | | | WifiMeasurement:wap | o | o | | Doran & Barnes Expires September 10, 2010 [Page 19] Internet-Draft CLIF March 2010 | WifiMeasurement:wap:ssid | o | | | | WifiMeasurement:wap:bssid | o | o | | | WifiMeasurement:wap:apName | o | | | | WifiMeasurement:wap:location | o | | | | WifiMeasurement:wap:type | o | | | | WifiMeasurement:wap:channel | o | o | | | WifiMeasurement:wap:rssi | o | o | | | WifiMeasurement:wap:snr | o | o | | | WifiMeasurement:wap:rtt | o | | | | CellularMeasurement::Measurement | o | o | | | CellularMeasurement:radioType | | o | | | CellularMeasurement:carrier | | o | | | CellularMeasurement:tower | o | | | | CellularMeasurement:tower:mcc | o | o | | | CellularMeasurement:tower:mnc | o | o | | | CellularMeasurement:tower:cid | o | o | | | CellularMeasurement:tower:eucid | o | | | | CellularMeasurement:tower:rnc | o | | | | CellularMeasurement:tower:lac | o | o | | | CellularMeasurement:tower:nid | o | | | | CellularMeasurement:tower:sid | o | | | | CellularMeasurement:tower:baseid | o | | | | CellularMeasurement:tower:rssi | | o | | | CellularMeasurement:tower:timingAdvance | | o | | +-----------------------------------------+------+-------+----------+ Table 2 +-------------------------+------+-------+----------+ | CLIF Response | HELD | Gears | Parlay/X | +-------------------------+------+-------+----------+ | message | | | o | | uid | | o | o | | age | | | o | | uri | o | | | | location | o | | | | location:geo | o | o | o | | location:civic | o | o | | | location:civic:language | o | | | | location:civic:country | o | o | | | location:civic:a1 | o | o | | | location:civic:a2 | o | o | | | location:civic:a3 | o | o | | | location:civic:a4 | o | | | | location:civic:a5 | o | | | | location:civic:a6 | o | o | | | location:civic:prd | o | | | | location:civic:pod | o | | | Doran & Barnes Expires September 10, 2010 [Page 20] Internet-Draft CLIF March 2010 | location:civic:sts | o | | | | location:civic:hno | o | o | | | location:civic:hns | o | | | | location:civic:lmk | o | | | | location:civic:loc | o | | | | location:civic:name | o | | | | location:civic:pc | o | o | | | location:civic:bld | o | o | | | location:civic:unit | o | | | | location:civic:flr | o | | | | location:civic:room | o | | | | location:civic:plc | o | | | | location:civic:pcn | o | | | | location:civic:pobox | o | | | | location:civic:addcode | o | | | | location:civic:seat | o | | | | location:civic:rd | o | | | | location:civic:rdsec | o | | | | location:civic:rdbr | o | | | | location:civic:rdsubbr | o | | | | location:civic:prm | o | | | | location:civic:pom | o | | | | location:reference | o | | | | location:reference:uris | o | | | | Error | o | | | | Error:code | o | | o | | Error:message | o | | | +-------------------------+------+-------+----------+ Table 3 6.1. HELD This section will focus on how to use CLIF with the HELD protocol. +--------------------------------------+----------------------------+ | CLIF Request | HELD | +--------------------------------------+----------------------------+ | callback | | | language | | | accuracy | | | maxAge | | | responseTime | | | locationType | locationType | | Identifiers:uid | Identifiers:duid | | Identifiers:accessUsername | Identifiers:nai | | Identifiers:accessPassword | | | Identifiers:ip | Identifiers:ip | Doran & Barnes Expires September 10, 2010 [Page 21] Internet-Draft CLIF March 2010 | Identifiers:mac | Identifiers:mac | | Identifiers:port | Identifiers:tcpport,udppor | | | t | | Identifiers:uri | Identifiers:uri | | Identifiers:fqdn | Identifiers:fqdn | | Identifiers:Telephony | | | Identifiers:Telephony:msisdn | Identifiers:msisdn | | Identifiers:Telephony:imsi | Identifiers:imsi | | Identifiers:Telephony:imei | Identifiers:imei | | Identifiers:Telephony:min | Identifiers:min | | Identifiers:Telephony:mdn | Identifiers:mdn | | Identifiers:Telephony:hmcc | | | Identifiers:Telephony:hmnc | | | Measurement | | | Measurement:time | | | Measurement:expires | | | Measurement:samples | | | WifiMeasurement::Measurement | | | WifiMeasurement:nicType | | | WifiMeasurement:wap | | | WifiMeasurement:wap:ssid | | | WifiMeasurement:wap:bssid | | | WifiMeasurement:wap:apName | | | WifiMeasurement:wap:location | | | WifiMeasurement:wap:type | | | WifiMeasurement:wap:channel | | | WifiMeasurement:wap:rssi | | | WifiMeasurement:wap:snr | | | WifiMeasurement:wap:rtt | | | CellularMeasurement::Measurement | | | CellularMeasurement:radioType | | | CellularMeasurement:carrier | | | CellularMeasurement:tower | | | CellularMeasurement:tower:mcc | | | CellularMeasurement:tower:mnc | | | CellularMeasurement:tower:cid | | | CellularMeasurement:tower:eucid | | | CellularMeasurement:tower:rnc | | | CellularMeasurement:tower:lac | | | CellularMeasurement:tower:nid | | | CellularMeasurement:tower:sid | | | CellularMeasurement:tower:baseid | | | CellularMeasurement:tower:rssi | | | CellularMeasurement:tower:timingAdva | | | n ce | | +--------------------------------------+----------------------------+ Table 4 Doran & Barnes Expires September 10, 2010 [Page 22] Internet-Draft CLIF March 2010 +---------------+------------------+ | CLIF Response | HELD | +---------------+------------------+ | message | | | uid | | | age | | | uri | locationUriSet | | location | presence PIDF-LO | | Error | | | Error:code | Error:code | | Error:message | Error:message | +---------------+------------------+ Table 5 6.1.1. Location Request Message This section will focus on how to encode/decode a HELD Location Request message using CLIF. 6.1.2. Location Response Message This section will focus on how to encode/decode a HELD Location Response message using CLIF. 6.1.3. Error Message This section will focus on how to encode/decode a HELD Error message using CLIF. 6.2. Google Gears This section will focus on how to use CLIF with the Google Gears Geolocation network protocol. +-----------------------------------------+---------------------+ | CLIF Request | Gears | +-----------------------------------------+---------------------+ | callback | | | language | address_language | | accuracy | | | maxAge | | | responseTime | | | locationType | request_address | | Identifiers:uid | access_token | | Identifiers:accessUsername | | | Identifiers:accessPassword | | | Identifiers:ip | | Doran & Barnes Expires September 10, 2010 [Page 23] Internet-Draft CLIF March 2010 | Identifiers:mac | | | Identifiers:port | | | Identifiers:uri | | | Identifiers:fqdn | | | Identifiers:Telephony | | | Identifiers:Telephony:msisdn | | | Identifiers:Telephony:imsi | | | Identifiers:Telephony:imei | | | Identifiers:Telephony:min | | | Identifiers:Telephony:mdn | | | Identifiers:Telephony:hmcc | | | Identifiers:Telephony:hmnc | | | Measurement | | | Measurement:time | age | | Measurement:expires | | | Measurement:samples | | | WifiMeasurement::Measurement | [WiFi Data Object] | | WifiMeasurement:nicType | | | WifiMeasurement:wap | | | WifiMeasurement:wap:ssid | | | WifiMeasurement:wap:bssid | mac-address | | WifiMeasurement:wap:apName | | | WifiMeasurement:wap:location | | | WifiMeasurement:wap:type | | | WifiMeasurement:wap:channel | channel | | WifiMeasurement:wap:rssi | signal_strength | | WifiMeasurement:wap:snr | signal_to_noise | | WifiMeasurement:wap:rtt | | | CellularMeasurement::Measurement | [Cell Data Object] | | CellularMeasurement:radioType | radio_type | | CellularMeasurement:carrier | carrier | | CellularMeasurement:tower | | | CellularMeasurement:tower:mcc | mobile_country_code | | CellularMeasurement:tower:mnc | mobile_network_code | | CellularMeasurement:tower:cid | cell_id | | CellularMeasurement:tower:eucid | | | CellularMeasurement:tower:rnc | | | CellularMeasurement:tower:lac | location_area_code | | CellularMeasurement:tower:nid | | | CellularMeasurement:tower:sid | | | CellularMeasurement:tower:baseid | | | CellularMeasurement:tower:rssi | signal_strength | | CellularMeasurement:tower:timingAdvance | timing_advance | +-----------------------------------------+---------------------+ Table 6 Doran & Barnes Expires September 10, 2010 [Page 24] Internet-Draft CLIF March 2010 +-------------------------+--------------------------+ | CLIF Response | Gears | +-------------------------+--------------------------+ | message | | | uid | access_token | | age | | | uri | | | location | | | location:geo | Response location fields | | location:civic | | | location:civic:language | | | location:civic:country | address:country | | location:civic:a1 | address:region | | location:civic:a2 | address:county | | location:civic:a3 | address:city | | location:civic:a4 | | | location:civic:a5 | | | location:civic:a6 | address:street | | location:civic:prd | | | location:civic:pod | | | location:civic:sts | | | location:civic:hno | address:street_number | | location:civic:hns | | | location:civic:lmk | | | location:civic:loc | | | location:civic:name | | | location:civic:pc | address:postal_code | | location:civic:bld | address:premises | | location:civic:unit | | | location:civic:flr | | | location:civic:room | | | location:civic:plc | | | location:civic:pcn | | | location:civic:pobox | | | location:civic:addcode | | | location:civic:seat | | | location:civic:rd | | | location:civic:rdsec | | | location:civic:rdbr | | | location:civic:rdsubbr | | | location:civic:prm | | | location:civic:pom | | | location:reference | | | location:reference:uris | | | Error | | | Error:code | | | Error:message | | +-------------------------+--------------------------+ Doran & Barnes Expires September 10, 2010 [Page 25] Internet-Draft CLIF March 2010 Table 7 6.2.1. Location Request Message This section will focus on how to encode/decode a Gears Location Request message using CLIF. Here is an example of a Gears Location Request message: Doran & Barnes Expires September 10, 2010 [Page 26] Internet-Draft CLIF March 2010 { "version": "1.1.0", "host": "maps.google.com", "access_token": "2:k7j3G6LaL6u_lafw:4iXOeOpTh1glSXe", "home_mobile_country_code": 310, "home_mobile_network_code": 410, "radio_type": "gsm", "carrier": "Vodafone", "request_address": true, "address_language": "en_GB", "location": { "latitude": 51.0, "longitude": -0.1 }, "cell_towers": [ { "cell_id": 42, "location_area_code": 415, "mobile_country_code": 310, "mobile_network_code": 410, "age": 0, "signal_strength": -60, "timing_advance": 5555 }, { "cell_id": 88, "location_area_code": 415, "mobile_country_code": 310, "mobile_network_code": 580, "age": 0, "signal_strength": -70, "timing_advance": 7777 } ], "wifi_towers": [ { "mac_address": "01-23-45-67-89-ab", "signal_strength": 8, "age": 0 }, { "mac_address": "01-23-45-67-89-ac", "signal_strength": 4, "age": 0 } ] } Figure 1: Gears Location Request Message [http://code.google.com/apis/gears/geolocation_network_protocol.html] Doran & Barnes Expires September 10, 2010 [Page 27] Internet-Draft CLIF March 2010 Specifications for encoding/decoding fields in the Gears Location Request: version: The Gears "version" parameter is specific to the Google Gears protocol and therefore does not get stored in the CLIF model. When encoding a Google Gears request from a CLIF request object, the encoder MUST generate the version parameter on its own. When decoding a Google Gears request and storing the data in a CLIF object, the decoder MUST not store the version number in the model, though it MAY choose to store or use it outside CLIF for some application-specific purpose. host: The Gears "host" parameter is specific to the Google Gears protocol and therefore does not get stored in the CLIF model. When encoding a Google Gears request from a CLIF request object, the encoder MUST generate the host parameter on its own. When decoding a Google Gears request, the decoder MUST not store the host parameter in a CLIF object, though it MAY choose to store or use it outside CLIF for some application-specific purpose. access_token: The Gears "access_token" parameter MAY be stored in the Identifiers:uid field of the CLIF request object. In the Gears protocol, this parameter is set by the server in a response message to be used for future requests. Therefore, if this field is empty in the CLIF model, a Gears encoder MUST NOT attempt to generate it. If the encoder has an access_token that was generated by a Gears server to use for requests, it SHOULD insert this access_token into requests and ignore the Identifiers:uid field. If the encoder does not have its own Gears access_token, it MAY check the Identifiers:uid field for an access_token, but it MUST verify that any value stored in this field is a valid Gears access_tokn, as this field can store other unique identifiers. An example of a situation where it would be safe for the encoder to use the Identifiers:uid field as a Gears access_token would be when it has full knowledge of how this field was propogated and knows that it is being used to store Gears access_tokes (e.g., a decoder accepting only Gears location requests). A Gears decoder MAY store the access_token value in the Identifiers:uid field when decoding a Gears request. home_mobile_country_code: The Gears "home_mobile_country_code" parameter MUST be stored in the Identifiers:Telephony:hmcc field of the CLIF request object. An encoder can check this field when encoding a Gears Location Request message, and if it has a value it MAY encode it as the value for the home_mobile_country_code parameter in the Gears request. When decoding a Gears Location Request message, a home_mobile_country_code MUST be stored in the Identifiers:Telephony:hmcc field of the CLIF request object. Doran & Barnes Expires September 10, 2010 [Page 28] Internet-Draft CLIF March 2010 home_mobile_network_code: The Gears "home_mobile_network_code" parameter MUST be stored in the Identifiers:Telephony:hmnc field of the CLIF request object. An encoder can check this field when encoding a Gears Location Request message, and if it has a value it MAY encode it as the value for the home_mobile_network_code parameter in the Gears request. When decoding a Gears Location Request message, a home_mobile_network_code MUST be stored in the Identifiers:Telephony:hmnc field of the CLIF request object. radio_type: carrier: request_address: address_language: location: latitude: longitude: cell_towers: wifi_towers: 6.2.2. Location Response Message This section will focus on how to encode/decode a Gears Location Response message using CLIF request object. 6.3. Parlay/X This section will focus on how to use CLIF request object with the Parlay/X protocol. Doran & Barnes Expires September 10, 2010 [Page 29] Internet-Draft CLIF March 2010 +------------------------------+------------------------------------+ | CLIF Request | Parlay/X | +------------------------------+------------------------------------+ | callback | requester | | language | | | accuracy | requestedAccuracy, | | | acceptableAccuracy | | maxAge | maximumAge | | responseTime | responseTime | | locationType | | | Identifiers:uid | reference, correlator | | Identifiers:accessUsername | | | Identifiers:accessPassword | | | Identifiers:ip | | | Identifiers:mac | | | Identifiers:port | | | Identifiers:uri | address | | Identifiers:fqdn | | | Identifiers:Telephony | | | Identifiers:Telephony:msisdn | | | Identifiers:Telephony:imsi | | | Identifiers:Telephony:imei | | | Identifiers:Telephony:min | | | Identifiers:Telephony:mdn | | | Identifiers:Telephony:hmcc | | | Identifiers:Telephony:hmnc | | +------------------------------+------------------------------------+ Table 8 Doran & Barnes Expires September 10, 2010 [Page 30] Internet-Draft CLIF March 2010 +----------------+---------------------------------------+ | CLIF Response | Parlay/X | +----------------+---------------------------------------+ | message | LocationData:reportStatus | | uid | correlator | | age | LocationInfo:timestamp | | uri | | | location | | | location:geo | LocationInfo | | location:civic | | | Error | | | Error:code | reason, LocationData:errorInformation | | Error:message | | +----------------+---------------------------------------+ Table 9 6.3.1. getLocation Request Message This section will focus on how to encode/decode a Parlay/X getLocation Request using the CLIF. 6.3.2. getLocation Response Message This section will focus on how to encode/decode a Parlay/X getLocation Response using CLIF. 6.3.3. getLocationForGroup Request Message This section will focus on how to encode/decode a Parlay/X getLocationForGroup Request using CLIF. 6.3.4. getLocationForGroup Response Message This section will focus on how to encode/decode a Parlay/X getLocationForGroup Response using CLIF. 7. Applications This section provides use cases for CLIF: o Implementing Single Protocol [Protocol A] Client * Pre-designed, pre-implemented data model - developers will not have to design and implement their own Doran & Barnes Expires September 10, 2010 [Page 31] Internet-Draft CLIF March 2010 * The client is already designed to support additional protocols if they are later added o Implementing Multiple Protocol [Protocols A, B, C] Client * Single Data Model, Multiple Protocols o Transitioning from Protocol A to Protocol B * Mapping in this docuemnt provides instructions for how to map Protocol A to CLIF to Protocol B * All Protocol A code / components / assets can still be used, just add a translation layer o Reusing Server Components * A location server can accept multiple protocols on the front- end, normalize them all to CLIF, allowing other parts of the server to be usable for all protocols (eg, logging, caching) o Interoperability of Protocols * Implement a location server that accepts [Protocol A] Requests, in case of [Protocol A] failure, it degrades to use [Protocol B], and the translation / [Protocol B] query is done server- side, with the [Protocol B] response being translate back to [Protocol A] to send to the client. 8. Privacy Considerations [Text here] 9. Security Considerations [Text here] 10. References 10.1. Normative References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Schulzrinne, H., Tschofenig, H., Morris, J., Cuellar, J., Polk, Doran & Barnes Expires September 10, 2010 [Page 32] Internet-Draft CLIF March 2010 J., and J. Rosenberg, "Common Policy: A Document Format for Expressing Privacy Preferences", RFC 4745, February 2007. [3] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [4] Schulzrinne, H., Tschofenig, H., Morris, J., Cuellar, J., and J. Polk, "Geolocation Policy: A Document Format for Expressing Privacy Preferences for Location Information", draft-ietf-geopriv-policy-21 (work in progress), January 2010. [5] Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, "HTTP Enabled Location Delivery (HELD)", draft-ietf-geopriv-http-location-delivery-16 (work in progress), August 2009. [6] Polk, J., "Dynamic Host Configuration Protocol (DHCP) IPv4 and IPv6 Option for a Location Uniform Resource Identifier (URI)", draft-ietf-geopriv-dhcp-lbyr-uri-option-07 (work in progress), March 2010. 10.2. Informative References [7] Peterson, J., "A Presence-based GEOPRIV Location Object Format", RFC 4119, December 2005. [8] Peterson, J., Hardie, T., and J. Morris, "Implications of 'retransmission-allowed' for SIP Location Conveyance", RFC 5606, August 2009. [9] Marshall, R., "Requirements for a Location-by-Reference Mechanism", draft-ietf-geopriv-lbyr-requirements-09 (work in progress), November 2009. [10] Tschofenig, H. and H. Schulzrinne, "GEOPRIV Layer 7 Location Configuration Protocol; Problem Statement and Requirements", draft-ietf-geopriv-l7-lcp-ps-10 (work in progress), July 2009. [11] Polk, J., Schnizlein, J., Linsner, M., Thomson, M., and B. Aboba, "Dynamic Host Configuration Protocol Options for Coordinate-based Location Configuration Information", draft-ietf-geopriv-rfc3825bis-09 (work in progress), March 2010. Doran & Barnes Expires September 10, 2010 [Page 33] Internet-Draft CLIF March 2010 Authors' Addresses Kevin M. Doran BBN Technologies 9861 Broken Land Parkway Columbia, MD 21046 US Phone: +1 410 290 6175 Email: kdoran@bbn.com Richard L. Barnes BBN Technologies 9861 Broken Land Parkway Columbia, MD 21046 US Phone: +1 410 290 6169 Email: rbarnes@bbn.com Doran & Barnes Expires September 10, 2010 [Page 34]