idnits 2.17.1 draft-ietf-geopriv-binary-lci-01.txt: -(108): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 323. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 334. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 341. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 347. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 10, 2007) is 5982 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 3825 (ref. '1') (Obsoleted by RFC 6225) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GEOPRIV J. Schnizlein 3 Internet-Draft M. Linsner 4 Intended status: Informational Cisco Systems 5 Expires: June 10, 2008 December 10, 2007 7 Binary to Decimal Conversion for Location Configuration Information 8 draft-ietf-geopriv-binary-lci-01 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on June 10, 2008. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2007) 39 Abstract 41 This document describes the nature of the data expressed in the 42 geographic LCI defined in RFC 3825, and includes examples of 43 conversion from its binary format to decimal character strings. 45 Table of Contents 47 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 2 48 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 2 49 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 50 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 5. Programming Hints . . . . . . . . . . . . . . . . . . . . . 4 52 6. Calculation of LCI values . . . . . . . . . . . . . . . . . 5 53 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 6 54 8. Security . . . . . . . . . . . . . . . . . . . . . . . . . . 6 55 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 9.1 Normative References . . . . . . . . . . . . . . . . . . 7 57 9.2 Informative References . . . . . . . . . . . . . . . . . 7 58 10. Author's Address . . . . . . . . . . . . . . . . . . . . . . 7 60 1. Terminology 62 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 63 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 64 this document are to be interpreted as described in [0]. 66 2. Definitions 68 This document uses the following terms to describe geo LCI binary to 69 decimal conversion: 71 Location Configuration Information: (LCI) An object that carries 72 location information. LCI has no ability to express privacy rules as 73 outlined in [3] and [4], therefore is considered part of the 'sighting' 74 function. For purposes of this discussion, all references to LCI refer 75 to its use in [1]. 77 GNU Compiler Collection: (GCC) The GNU Compiler Collection is a set 78 of programming language compilers produced by the GNU Project. 80 3. Introduction 82 The LCI encodes a point's latitude, longitude and altitude, along with 83 the resolution of that point. LCI does not encode boundaries of an 84 arbitrary region. The resolution is nothing more than the 85 representation of significant digits for the fixed-length, binary values 86 in the LCI. This document corrects misinterpretations of the non- 87 normative examples in [1]. 89 Format conversion is required between the binary LCI that a host can 90 receive through DHCP [1] or LLDP-MED [5] and the decimal representation 91 used by applications, e.g. PIDF-LO [2]. This conversion could be used 92 by a host that provides its location to another party with the privacy 93 rules of the [2], including to a server authorized to redistribute the 94 information. It is unclear why anyone would need to convert from the 95 geographic-coordinate location format of [2] to the LCI. 97 4. Overview 99 This section provides an overview of the programming hints in the next 100 section for the translation from the efficient binary representation of 101 the LCI [1][5] to the decimal string representation of geographic 102 location used in PIDF-LO [2], for example. GCC syntax is used because 103 it is well known. The binary values are converted to decimal, with the 104 invalid bits removed and with the number of significant digits 105 determined by the resolution of the binary values. 107 After unpacking the network-order bytes of the LCI into C variables 108 sufficiently large to accommodate the fields, the sign bit of the two�s- 109 complement integers are extended to the size of the variable. The sign 110 bit at 34 bits to the left is tested with an octal constant containing 111 33 bits in 11 octal-digits of zero. If negative, the sign is extended: 112 the upper bits are set to �1� by ORing the value with a value of 113 minus-one with the lower 34 bits inverted to zero with XOR. This 114 operation is safe to perform more than once. 116 Because [1] says "Contents beyond the claimed resolution MAY be 117 randomized ...", these contents are erased, i.e. set to zero. The 118 number of bits to erase is the field length minus the resolution of the 119 value in that field. A mask is constructed by left-shifting a one into 120 the right of the mask for as many bits as to be erased. ANDing the 121 inverse of the mask with the value erases the invalid bits. 123 The fixed-point fraction values are scaled into a floating-point 124 (double for enough precision) by dividing by the constant reflecting the 125 number of fractional bits. Note that latitude and longitude have 25 126 bits of fraction, while altitude has only 22 bits. The number of 127 significant digits to the right of the decimal point is the resolution 128 minus its integer portion, scaled by 3 decimal digits for 10 binary 129 digits because 10 to the 3rd = 1000 approximates 2 to the 10th = 1024. 131 5. Programming hints 133 The LCI format is as follows: 135 0 1 2 3 136 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 137 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 138 | Code 123 | 16 | LaRes | Latitude + 139 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 140 | Latitude (cont'd) | LoRes | + 141 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 142 | Longitude | 143 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 144 | AT | AltRes | Altitude | 145 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 146 | Alt (cont'd) | Datum | 147 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 149 Assume the following element values have been unpacked from the 16 bytes 150 of the wire protocol above. 152 struct LCIoption { 153 int8_t code; /* DHCP LCI option code = 123 */ 154 int8_t length; /* length 16 bytes - not incl code + length */ 155 int8_t LaRes; /* Latitude Resolution 6 bits */ 156 int64_t Latitude; /* Latitude 34 bits, 25 fractional */ 157 int8_t LoRes; /* Longitude Resolution 6 bits */ 158 int64_t Longitude; /* Latitude 34 bits, 25 fractional */ 159 int8_t AltType; /* Altitude Type 4 bits */ 160 int8_t AltRes; /* Altitude Resolution 6 bits */ 161 int64_t Altitude; /* Altitude 30 bits 22 bits Fraction */ 162 int8_t Datum; /* Datum code 8 bits */ 163 }; 165 Because the latitude, longitude, and altitude values are twos complement 166 of non-standard length, they require sign-extension that is not built 167 into typical variable types. For the Latitude example: 169 struct LCIoption OptIn; 171 /* if negative 34-bit field, set all one-bits above the 34-bit field */ 172 if (OptIn.Latitude & 0100000000000LL) 173 OptIn.Latitude = OptIn.Latitude | (-1 ^ 0177777777777LL) 174 /* XOR '^' to flip one bits to zero before ORing in the field */ 175 Translation from the binary resolution of the LCI to the correct number 176 of significant decimal digits in the character string representation 177 used for numbers in PIDF-LO is as in the following example for Latitude: 179 int8_t eraseBits = 34 - OptIn.LaRes; 180 int64_t mask = 0LL; 181 if (eraseBits > 0) while (eraseBits--) mask = (mask << 1) | 1; 183 /* invert mask and AND to zero invalid bits */ 184 OptIn.Latitude &= ~mask; 186 double latitude = OptIn.Latitude / exp2 (25); 187 /* scale integer for 25 bits of fraction */ 188 int8_t LatFractDigits = (OptIn.LaRes - 9) * 3 / 10; 189 /* deduct integer part, 2 to 10 ~= 10 to 3 */ 191 if (LatFractDigits < 0) LatFractDigits = 0; 192 /* report integer part if resolution is lower */ 193 printf ("%11.*F\n", LatFractDigits, latitude); 195 6. Calculation of LCI values 197 Since the Global Positioning System (GPS) or survey methods do not 198 provide location in the LCI format, this section illustrates how a 199 network administrator might calculate the values in preparation for 200 delivering them to hosts connected to her network. 202 Where geographic location is expressed with the correct number of 203 significant digits, it is easy to compute resolution because 3 decimal 204 digits approximate 10 bits. The number of digits to the right of the 205 decimal point, times 10, divided by 3 is the number of fractional bits. 206 Adding 9 for the integer part yields the resolution. 208 Where a geographic location comes with an explicit error specification, 209 this error can be translated into the resolution of the LCI. If the 210 error measure is in distance (e.g. meters) rather than degrees, the 211 conversion of longitude to degrees depends on the distance from the 212 equator. Dividing the error distance by the distance for one degree 213 (computed with the method described at [6]) yields the error in 214 (presumably fractional) degrees. 216 double DegreeError; 217 int64_t FixedPntErrDeg = degreeError * exp2 (25); 218 /* convert error to fixed point 25-bit */ 220 int64_t TopBit = 0100000000000LL; 221 if (FixedPntErrDeg & TopBit) FixedPntErrDeg = - FixedPntErrDeg; 222 /* if negative make positive */ 224 /* shift test bit to find first non-zero error */ 225 int8_t resolution = 1; 226 while ((FixedPntErrDeg & (TopBit >>= 1)) == 0LL) { 227 if (TopBit == 0LL) break; 228 resolution++; 229 } 230 /* the shift count is the number of valid bits */ 232 If all that is available is the bounding points of a region, the 233 difference between the extremes and the center in both latitude and 234 longitude estimates the error in degrees, which can be converted to 235 resolution as above. Find the maximum and minimum of both, calculate 236 the value of the latitude/longitude as the average, and half the 237 difference as the error. 239 For the example bounds ranging about 0.5 meters in distances across 240 about 32 degrees, the binary and decimal values are as follows: 242 binary decimal 243 000011111.1111111111111111111001110 31.99999850 244 000100000.0000000000000000001011100 32.00000274 246 001000000.0000000000000000000101010 64.00000124 sum 247 000100000.0000000000000000000010101 32.00000062 average 248 000000000.0000000000000000010001110 00.00000423 difference 250 With 26 bits above the difference, which is twice the error, this 251 example yields 27 bits of resolution (remembering to add 9 bits for left 252 of the binary point). 254 7. IANA Considerations 256 No IANA Considerations 258 8. Security 260 This document discusses binary to decimal conversion within an end host, 261 which raises no particular security considerations. 263 9. References 265 9.1 Normative References 267 [0] RFC 2119 Key words for use in RFCs to Indicate Requirement Levels, 268 S. Bradner. March 1997. 270 [1] RFC 3825 Dynamic Host Configuration Protocol Option for 271 Coordinate-based Location Configuration Information. J. Polk, J. 272 Schnizlein, M. Linsner. July 2004. 274 [2] RFC 4119 A Presence-based GEOPRIV Location Object Format. J. 275 Peterson. December 2005. 277 [3] RFC 3693 Geopriv Requirements. J. Cuellar, J. Morris, D. Mulligan, 278 J. Peterson, J. Polk. February, 2004. 280 [4] RFC 3694 Threat Analysis of the Geopriv Protocol. M. Danley, D. 281 Mulligan, J. Morris, J. Peterson. February 2004 283 9.2 Informative References 285 [5] TIA-1057 (LLDP-MED) The Telecommunications Industry Association 286 (TIA) standard, "Telecommunications - IP Telephony Infrastructure - 287 Link Layer Discovery Protocol (LLDP) for Media Endpoint Devices. 289 [6] "Problem 2A.: Calculate path length along a meridian given 290 starting and ending coordinates". Andy McGovern. April 2004 291 http://www.codeguru.com/Cpp/Cpp/algorithms/general/article.php/c5 292 115 294 10. Author's Address 296 John Schnizlein 297 Cisco Systems, Inc. 298 Fort Washington, MD, USA 299 Email: john.schnizlein@cisco.com 301 Marc Linsner 302 Cisco Systems, Inc. 303 Marco Island, Florida, USA 304 Email: marc.linsner@cisco.com 306 Comments are solicited and should be addressed to the working group's 307 mailing list at geopriv@ietf.org and/or the authors. 309 Full Copyright Statement 311 Copyright (C) The IETF Trust (2007). 313 This document is subject to the rights, licenses and restrictions 314 contained in BCP 78, and except as set forth therein, the authors 315 retain all their rights. 317 This document and the information contained herein are provided on an 318 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 319 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 320 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 321 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 322 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 323 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 325 Intellectual Property 327 The IETF takes no position regarding the validity or scope of any 328 Intellectual Property Rights or other rights that might be claimed to 329 pertain to the implementation or use of the technology described in 330 this document or the extent to which any license under such rights 331 might or might not be available; nor does it represent that it has 332 made any independent effort to identify any such rights. Information 333 on the procedures with respect to rights in RFC documents can be 334 found in BCP 78 and BCP 79. 336 Copies of IPR disclosures made to the IETF Secretariat and any 337 assurances of licenses to be made available, or the result of an 338 attempt made to obtain a general license or permission for the use of 339 such proprietary rights by implementers or users of this 340 specification can be obtained from the IETF on-line IPR repository at 341 http://www.ietf.org/ipr. 343 The IETF invites any interested party to bring to its attention any 344 copyrights, patents or patent applications, or other proprietary 345 rights that may cover technology that may be required to implement 346 this standard. Please address the information to the IETF at 347 ietf-ipr@ietf.org. 349 Acknowledgment 351 Funding for the RFC Editor function is provided by the IETF 352 Administrative Support Activity (IASA).