Geopriv Working Group James Polk
Internet-Draft Cisco Systems
Expires: April 16th, 2007 Oct 16th, 2006
A Geopriv Registry for Location-based Error Response Codes
draft-polk-geopriv-location-based-error-registry-00
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of 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 April 8th, 2007.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document IANA registers a list of GEOPRIV location-specific
error response indications, to be used by signaling protocols
describing a location-based error experienced by an intermediary or
recipient endsystem. For example, the registered values here can be
placed in a SIP Reason header contained within a 424 (Bad Location
Information) response, or in a Location-to-Service Translation
(LoST) query failure, giving specific meaning to the reason for the
error. This additional information is to provide the location
transmitter more granular information about what was wrong with the
supplied location in the original request message.
Polk Expires April, 2006 [Page 1]
Internet-Draft Location Error Code Registry Oct 2006
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1 Conventions used in this document . . . . . . . . . . . . 3
2. Basic Operation of Location Error Messaging . . . . . . . . . 3
3. Failure Reasons to be Registered . . . . . . . . . . . . . . 5
3.1 Location Format Not Supported . . . . . . . . . . . . . . 6
3.2 Geo-location Format Desired Instead . . . . . . . . . . . 6
3.3 Civic-location Format Desired Instead . . . . . . . . . . 6
3.4 Unsupported Schema . . . . . . . . . . . . . . . . . . . . 7
3.5 Cannot Parse Location Supplied . . . . . . . . . . . . . . 7
3.6 Cannot Find Location . . . . . . . . . . . . . . . . . . . 8
3.7 Cannot Dereference . . . . . . . . . . . . . . . . . . . . 8
3.8 Conflicting Locations Supplied . . . . . . . . . . . . . . 8
3.9 Incomplete Location Supplied . . . . . . . . . . . . . . . 9
3.10 Dereference Timeout . . . . . . . . . . . . . . . . . . . 9
3.11 Cannot Process Dereference . . . . . . . . . . . . . . . . 9
4. LoST Error Codes . . . . . . . . . . . . . . . . . . . . . . 10
4.1 400 Bad Request . . . . . . . . . . . . . . . . . . . . . 10
4.2 403 Forbidden . . . . . . . . . . . . . . . . . . . . . . 10
4.3 404 Not Found . . . . . . . . . . . . . . . . . . . . . . 10
4.4 414 Location Error . . . . . . . . . . . . . . . . . . . . 10
4.5 500 Server Internal Error . . . . . . . . . . . . . . . . 10
4.6 501 Service Not Implemented . . . . . . . . . . . . . . . 10
4.7 504 Server Time-Out . . . . . . . . . . . . . . . . . . . 11
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1 Normative References . . . . . . . . . . . . . . . . . . 12
8.2 Informative References . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . 12
Intellectual Property and Copyright Statements . . . . . . . 12
1. Introduction
This document creates a registry of specific reasons for
location-based errors in certain protocol transactions. These
reasons can be included in other transport protocols to provide the
originator additional information that something was wrong with a
location related parameter or value during processing.
The intention here is to create a common set of location-specific
error codes to be used across multiple protocols so that when more
than one is used, the information is transferred between them in a
common way, should the error require original location sender
knowledge.
For example, SIP defines location conveyance in [ID-SIP-LOC].
Within that document a new error response was created, the 424 (Bad
Polk Expires April, 2006 [Page 2]
Internet-Draft Location Error Code Registry Oct 2006
Location Information). A SIP user agent (UA) receiving this 424
response would not be receiving enough information to know the
specifics about what was bad, just that the transaction's error had
to do with location supplied in the SIP request. [ID-SIP-LOC]
specifies that a [RFC3326] Reason header can be used in this 424
response to provide additional/more granular location-specific
information to the originating user agent client (UAC). [ID-SIP-
LOC] also created the "Geolocation" Reason protocol, as specified by
[RFC3326]. Within this Reason protocol, cause values provide
additional specific information to a recipient as to the reason for
the error message (in this case). These reason types are defined
here.
This document is not limited to use with a SIP Reason header. Other
text based protocols can use these location error types to provide
more granular causes for a message failure.
[NOTE: need to add what the reaction would be if used by LoST]
1.1 Conventions used in this document
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 [RFC2119].
2. Basic Operation of Location Error Messaging
The following explain the basic operation of location-based errors,
requiring transport back to the originator of a request message to
have a more detailed reason why a particular request message failed.
Figure 1. shows a request/response transaction between two
endpoints. Currently, if the reason for Bob's rejection of the
request is location related, there is no specified means of
indicating this in a response message. SIP, for example, has a
Reason header, but no current "protocol" is IANA registered to
indicate what about the location provided in the request caused the
error response. This registry takes advantage of [ID-SIP-LOC],
which registered the Geolocation protocol for the Reason header, to
give these location specific reasons for the failure.
Polk Expires April, 2006 [Page 3]
Internet-Draft Location Error Code Registry Oct 2006
Alice Bob
| |
| Request w/ Location |
|--------------------------------->|
| | **********************
| | * There is something *
| | * wrong with the *
| | * supplied Location *
| | **********************
| 424 (Bad Location Information) |
| with Location Error indication |
|<---------------------------------|
| |
Figure 1. User to User Location Error
The reason(s) for this type of error response currently are listed
in Section 3 of this document.
Figure 2. shows an example of Alice sending a Request message that
is processed by message routing server, which routes the message
based on the location (supplied in the request) of the requesting
user (Alice).
Alice Proxy1
| |
| Request w/ Location |
|--------------------------------->|
| | **********************
| | * There is something *
| | * wrong with the *
| | * supplied Location *
| | **********************
| 424 (Bad Location Information) |
| with Location Error indication |
|<---------------------------------|
| |
Figure 2. User to Routing Server Location Error
The reason(s) for this type of error response can be one or more of
many possibilities, including a malformed Location Object which
couldn't be parsed by the server to make a routing decision upon, or
an unknown location format, or an incomplete location object, or
conflicting location information within one or more location objects
in the message.
Figure 3. shows a more complex scenario involving a Alice's user
agent, a routing Proxy which performs a LoST query for the service
of the request (for example an emergency service PSAP URI
resolution).
Polk Expires April, 2006 [Page 4]
Internet-Draft Location Error Code Registry Oct 2006
Alice Proxy1 LoST Server
| | |
| Request w/ | |
| Location | |
|--------------------->| |
| | LoST Query |
| |----------------->|
| | | **********************
| | | * There is something *
| | | * wrong with the *
| | | * Location in Query *
| | | **********************
| | LoST Response |
| | w/ Error Indication
| |<-----------------|
| 424 (Bad Location) | |
| with Reason Header | |
| Location indication | |
|<---------------------| |
| | |
Figure 3. LoST Query Location Error
In the use-case of Figure 3., the error did not occur between
Alice's user agent and Proxy1, which means the error may not be
within the same protocol as the one used by Alice's endpoint. The
location based error also did not occur from Proxy1 towards the
ultimate destination, but either towards the LoST query or in the
LoST server itself. These LoST error codes are listed in Section 4
at this time.
This registry provides the means of transferring the location
specific error reason from the LoST protocol, received by Proxy1 in
this case, to the Signaling protocol used by Alice; in this case
SIP, but this can be another protocol (such as HTTP perhaps).
The key functionality here is the ability to take a LoST specific
error and convert it to a Reason header for the signaling leg from
the SIP server that received it towards Alice's UA.
IETF discussion should decide if the LoST unique error codes should
be returned raw to a UA, or if some of them should be harmonized
(i.e. consolidated) with the error codes listed below. A reason for
this is that perhaps not all UAs will understand each LoST error,
but make perfect sense within a LoST only transaction, nor may the
UA know what to do with certain ones either.
3. Failure Reasons to be Registered
Here is the list and description of each IANA registered location
Polk Expires April, 2006 [Page 5]
Internet-Draft Location Error Code Registry Oct 2006
error reason code. If the location generator were to receive one of
these indications in a SIP response, it would be in a Reason header.
The protocol field of this Reason header would be "geolocation", as
defined in [ID-SIP-LOC]. Examples of the Reason header are given
for each indication below.
3.1 Location Format Not Supported
"Location Format not supported" means the location format supplied
in the request, by-value or by-reference, was not supported. This
cause means the recipient understood that location was included in
the message, but the format is not supported. If the format is
understood, but not desired, a cause=2 or cause=3 response SHOULD be
returned.
Cause value: 1
Default text string: Location format not supported
An example usage in a SIP Reason header:
Reason: geolocation; cause=1; Location format not supported
3.2 Geo-location Format Desired Instead
"Geo-location Format Desired" means the location format supplied in
the request (here probably civic-location), by-value or
by-reference, was understood and supported, but that the recipient,
or an application on the recipient prefers a geo-location format be
supplied instead.
A typical reaction to receiving this cause value is to resend the
original message with the geo-location format included.
Cause value: 2
Default text string: Geo-location Format Desired
An example usage in a SIP Reason header:
Reason: geolocation; cause=2; Geo-location Format Desired
3.3 Civic-location Format Desired Instead
"Civic-location Format Desired" means the location format supplied
in the request (here probably geo-location), by-value or
by-reference, was understood and supported, but that the recipient,
or an application on the recipient prefers a civic-location format
be supplied instead.
Polk Expires April, 2006 [Page 6]
Internet-Draft Location Error Code Registry Oct 2006
A typical reaction to receiving this cause value is to resend the
original message with the civic-location format included.
Cause value: 3
Default text string: Civic-location Format Desired
An example usage in a SIP Reason header:
Reason: geolocation; cause=3; Civic-location Format Desired
3.4 Unsupported Schema
(NOTE: do we articulate which one is wanted with separate error codes?
i.e. one for sip, one for sips, one for http, etc)
"Unsupported Schema" means the location dereferencer cannot
dereference use the location-by-reference URI supplied because it
does not support the necessary protocol to do this. For example, if
an http-URL is supplied, but the dereferencer does not have http
running on that machine, it cannot dereference the location of the
sender.
A typical reaction to receiving this error would be for the location
sender to send a URI with a different schema.
Cause value: 4
Default text string: unsupported schema
An example usage in a SIP Reason header:
Reason: geolocation; cause=4; unsupported schema
3.5 Cannot Parse Location Supplied
"Cannot parse location supplied" means the location provided,
whether by-value or by-reference in a request is not well formed.
Cause value: 5
Default text string: Cannot parse location supplied
An example usage in a SIP Reason header:
Reason: geolocation; cause=5; Cannot parse location supplied
Polk Expires April, 2006 [Page 7]
Internet-Draft Location Error Code Registry Oct 2006
3.6 Cannot Find Location
"Cannot find location" means location should have been in the
message received, but the recipient cannot find it, either because
it is not in the message, or it is encrypted/opaque. The location
of the sender's location in a SIP message is identified in a
Location header. A cid:URI indicates the location is by-value in a
message body. A schema-URI indicates the location is by-reference
on a remote node to be dereferenced.
A typical reaction to receiving this error would be for the location
sender to verify it has indeed included location in the new request.
Another consideration would be for the location sender to not
encrypt the location in the request message.
Cause value: 6
Default text string: Cannot find location
An example usage in a SIP Reason header:
Reason: geolocation; cause=6; Cannot find location
3.7 Cannot Dereference (Location-URI returns an error)
"Cannot dereference" means the act of dereferencing failed to return
the target's location. This may mean the URI is bad, or the
referencable server some other error to the dereference request.
Cause value: 7
Default text string: Cannot dereference
An example usage in a SIP Reason header:
Reason: geolocation; cause=7; Cannot dereference
3.8 Conflicting Locations Supplied
"Conflicting Locations Supplied" means a location recipient received
more than one location for the location target, and is unsure what
to do because each location is towards a different position. This is
a case of too much information, and the information is conflicting.
A typical reaction to receiving this error is to reduce the number
of different locations supplied in the request, and send another
message to the location recipient.
Cause value: 8
Polk Expires April, 2006 [Page 8]
Internet-Draft Location Error Code Registry Oct 2006
Default text string: Conflicting Locations Supplied
An example usage in a SIP Reason header:
Reason: geolocation; cause=8; conflicting locations supplied
3.9 Incomplete Location Supplied
"Incomplete Location Supplied" means there is not enough location
information, by-value or by-reference, to determine where the
location target is.
A typical reaction to receiving this message is of the sender to
verify it has a complete position to convey.
Cause value: 9
Default text string: Incomplete location supplied
An example usage in a SIP Reason header:
Reason: geolocation; cause=9; Incomplete location supplied
3.10 Dereference Timeout
"Dereference Timeout" means that the dereferencing node has not
received the target's location within a reasonable timeframe. In
such a case, this cause value would be placed in a Reason header of
a 424 (Bad Location Information) response to the location sender.
Cause value: 10
Default text string: Dereference Timeout
An example usage in a SIP Reason header:
Reason: geolocation; cause=10; Dereference Timeout
3.11 Cannot Process Dereference
"Cannot process Dereference" means the dereference protocol has
received an overload condition error, indicating the location cannot
be accessed at this time. If a sip or sips schema were used to
dereference the target's location, and a 503 (Service Unavailable)
were the response to the dereference query, this cause=11 value
would be placed in the Reason header of a 424 (Bad Location
Information) response to the location sender.
Cause value: 11
Polk Expires April, 2006 [Page 9]
Internet-Draft Location Error Code Registry Oct 2006
Default text string: Cannot process Dereference
An example usage in a Reason header in SIP:
Reason: geolocation; cause=11; Cannot process Dereference
4. LoST Error Codes
The following is a set of error codes specific to between a
application server and a LoST server, in which the request message
contained location, and the error with the request is location
specific.
Currently, the LoST specific errors, currently parallel to the ones
in [ID-LOST] are maintaining the 3 digit error code numbers, to
remain consistent with what SIP uses. IETF consensus will sway this
to remain or change.
**Some, or all of the error messages below can be sent in whole from
the application signaling server to the user agent, relaying
through the intermediary server (for example, a SIP server).
4.1 400 Bad Request
The request could not be understood due to malformed syntax.
4.2 403 Forbidden
The server understood the request, but is refusing to fulfill it.
Authorization will not help, and the request SHOULD NOT be repeated.
4.3 404 Not Found
The server has definitive information that there is no service
mapping for the location specified.
4.4 414 Location Error
The location provided does not exist or fields within the location
information are contradictory.
4.5 500 Server Internal Error
The server encountered an unexpected condition that prevented it from
fulfilling the request. The client MAY retry the request after
several seconds.
4.6 501 Service Not Implemented
The server does not implement mapping for the service requested and
Polk Expires April, 2006 [Page 10]
Internet-Draft Location Error Code Registry Oct 2006
cannot provide an alternate service.
4.7 504 Server Time-Out
A server time-out occurs if the server contacted tries to recursively
resolve the query, but cannot get an answer within the time limit set
for the query.
5. IANA Considerations
This document creates the following IANA registrations defined in
Section 3 and 4 of this document, and recommends these registrations
be in a new table format similar to this:
Cause-Code Optional-Default-Text Reference
---------- --------------------- ---------
Cause=1 Location Format Not Supported [This doc]
Cause=2 Geo-location Format Desired [This doc]
Cause=3 Civic-location Format Desired [This doc]
Cause=4 Unsupported Schema [This doc]
Cause=5 Cannot Parse Location Supplied [This doc]
Cause=6 Cannot Find Location [This doc]
Cause=7 Cannot Dereference [This doc]
Cause=8 Conflicting Locations Supplied [This doc]
Cause=9 Incomplete Location Supplied [This doc]
Cause=10 Dereference Timeout [This doc]
Cause=11 Cannot Process Dereference [This doc]
Cause=400 Bad Request [This doc]
Cause=403 Forbidden [This doc]
Cause=404 Not Found [This doc]
Cause=414 Location Error [This doc]
Cause=500 Server Internal Error [This doc]
Cause=501 Service Not Implemented [This doc]
Cause=504 Server Time-Out [This doc]
Legend:
------
Cause-Code - Cause value for this indication
Optional-Default-Text - optional text string of indication
Reference - document which is the reference for this
cause value
6. Security Considerations
The security considerations of [RFC3261], [ID-SIP-LOC] and [ID-LoST]
apply to this document. All the security concerns and measures to
ensure a robust delivery of information applied to those 3 documents
cover any security concerns this document may have created.
Polk Expires April, 2006 [Page 11]
Internet-Draft Location Error Code Registry Oct 2006
7. Acknowledgements
To Allison Mankin for offering the motivation for this document's
idea. To the authors of [ID-LOST] for their existing error codes,
which were borrowed for this document.
8. References
8.1 Normative References
[ID-SIP-LOC] J. Polk, B. Rosen, "SIP Location Conveyance",
draft-ietf-sip-location-conveyance-04.txt, "work in
progress", September 2006
[RFC3326] H. Schulzrinne, D. Oran, G. Camarillo, "The Reason Header
Field for the Session Initiation Protocol (SIP)", RFC 3326
Reason Header, December 2002
[ID-LoST] T. Hardie, H. Schulzrinne, A. Newton, H. Tschofenig, "LoST:
A Location-to-Service Translation Protocol",
draft-ietf-ecrit-lost-00.txt, "work in progress", September
2006
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3261] J. Rosenberg, H. Schulzrinne, G. Camarillo, A. Johnston, J.
Peterson, R. Sparks, M. Handley, and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, May 2002.
8.2 Informative References
None at this time
Author's Address
James M. Polk
Cisco Systems, Inc.
Colleyville, Texas 76034
USA
Phone: +1-817-271-3552
Email: jmpolk@cisco.com
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed
to pertain to the implementation or use of the technology described
Polk Expires April, 2006 [Page 12]
Internet-Draft Location Error Code Registry Oct 2006
in this document or the extent to which any license under such
rights might or might not be available; nor does it represent that
it has made any independent effort to identify any such rights.
Information on the procedures with respect to rights in RFC
documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use
of such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository
at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Disclaimer of Validity
This document and the information contained herein are provided on
an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement
Copyright (C) The Internet Society (2006). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Polk Expires April, 2006 [Page 13]