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 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
2.  Definitions
3.  Data Model Overview
4.  Request parameters
    4.1.  General
        4.1.1.  Callback
        4.1.2.  Language
        4.1.3.  Response Accuracy
        4.1.4.  Response Age
        4.1.5.  Response Time
        4.1.6.  Response Location Type
    4.2.  Identifiers
        4.2.1.  Unique Identifier (UID)
        4.2.2.  Network Access Identifier (NAI)
        4.2.3.  Network Access Password
        4.2.4.  Group Identifier
        4.2.5.  IP Address
        4.2.6.  MAC Address
        4.2.7.  Port Number
        4.2.8.  URI
        4.2.9.  Fully Qualified Domain Name
        4.2.10.  Telephony
            4.2.10.1.  Mobile Station International Subscriber Dial Number (MSISDN)
            4.2.10.2.  International Mobile Subscriber Identity (IMSI)
            4.2.10.3.  International Mobile Equipment Identifier (IMEI)
            4.2.10.4.  Mobile Identification Number (MIN)
            4.2.10.5.  Mobile Directory Number (MDN)
            4.2.10.6.  Home Mobile Country Code
            4.2.10.7.  Home Mobile Network Code
    4.3.  Measurement
        4.3.1.  Timestamp
        4.3.2.  Expires
        4.3.3.  Samples
        4.3.4.  WifiMeasurement
            4.3.4.1.  NIC Type
            4.3.4.2.  Wireless Access Point (WAP)
        4.3.5.  CellularMeasurement
            4.3.5.1.  Radio Type
            4.3.5.2.  Carrier
            4.3.5.3.  Cellular Tower
        4.3.6.  WiMAX
        4.3.7.  GNSS
        4.3.8.  w16e
    4.4.  Other parameters
5.  Response parameters
    5.1.  General parameters
        5.1.1.  Message
        5.1.2.  Age
        5.1.3.  Unique Identifer (UID)
    5.2.  Location Reference
    5.3.  Location Oject [PIDF-LO]
        5.3.1.  Geodetic location
        5.3.2.  Civic location
    5.4.  Error
        5.4.1.  Error Code
        5.4.2.  Error Message
6.  Protocol mapping summary
    6.1.  HELD
        6.1.1.  Location Request Message
        6.1.2.  Location Response Message
        6.1.3.  Error Message
    6.2.  Google Gears
        6.2.1.  Location Request Message
        6.2.2.  Location Response Message
    6.3.  Parlay/X
        6.3.1.  getLocation Request Message
        6.3.2.  getLocation Response Message
        6.3.3.  getLocationForGroup Request Message
        6.3.4.  getLocationForGroup Response Message
7.  Applications
8.  Privacy Considerations
9.  Security Considerations
10.  References
    10.1.  Normative References
    10.2.  Informative References
§  Authors' Addresses

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.

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 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [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:

• HELD [ref:draft-ietf-geopriv-http-location-delivery]
• MLP [ref]
• Parlay/X [ref] (when used with "get"-style requests)
• 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):

• Parlay/X [ref] (when used with "notification"-style requests)
• LOCSIP [ref]
• 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, 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].

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:

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.

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

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.

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

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

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.

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

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

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

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.

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.

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:

6.1.  HELD

This section will focus on how to use CLIF with the HELD protocol.

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.

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:

{
  "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
    }
  ]
}

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.

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.

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:

• Implementing Single Protocol [Protocol A] Client
  • Pre-designed, pre-implemented data model - developers will not have to design and implement their own
  • The client is already designed to support additional protocols if they are later added
• Implementing Multiple Protocol [Protocols A, B, C] Client
  • Single Data Model, Multiple Protocols
• 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
• 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)
• 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

10.2. Informative References

Authors' Addresses