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]