idnits 2.17.1 draft-sbi-paws-protocol-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([IETF-PAWS-03], [FCC10-174]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 5, 2012) is 4407 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-15) exists of draft-ietf-paws-problem-stmt-usecases-rqmts-03 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Applications Area Working Group D. Joslyn 2 Internet Draft R. Roberts 3 Intended status: Standards Track Spectrum Bridge, Inc. 4 Expires: September 2012 March 5, 2012 6 Protocol for Communication between White Space Device and White 7 Space Database 8 draft-sbi-paws-protocol-00.txt 10 Status of this Memo 12 This Internet-Draft is submitted in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html 31 This Internet-Draft will expire on September 5, 2012. 33 Copyright Notice 35 Copyright (c) 2012 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. 45 Abstract 47 This document defines an application protocol for WSDB services 48 provided to TV Band Devices (TVBDs). The protocol complies with FCC 49 Rules/Requirements [FCC 10-174] and in the context of operating an 50 FCC certified database, it also complies with requirements defined by 51 IETF PAWS [IETF-PAWS-03]. We believe this protocol can be easily 52 extended to include the remaining requirements not already satisfied 53 from the IETF PAWS requirements. 55 Table of Contents 57 1. Introduction...................................................2 58 2. Conventions and Terminology....................................3 59 2.1. Conventions used in this document.........................3 60 2.2. Terminology...............................................3 61 3. Protocol Stack.................................................4 62 4. Protocol Definition............................................4 63 4.1. Registration..............................................5 64 4.1.1. Registration Request Message.........................6 65 4.2. Channel List Request......................................7 66 4.2.1. Channel List Request Message.........................8 67 4.2.2. Channel List Response................................9 68 4.3. FCC ID Verification Request..............................10 69 4.3.1. FCC ID Verification Request Message.................10 70 4.3.2. FCC ID Verification Response........................11 71 4.4. Data Objects.............................................11 72 4.5. Timers...................................................13 73 4.6. Status Return Codes......................................14 74 5. Formal Syntax.................................................15 75 6. IANA Considerations...........................................15 76 7. Security Considerations.......................................15 77 8. Conclusions...................................................15 78 9. Acknowledgments...............................................15 79 10. References...................................................15 80 10.1. Normative References....................................15 81 10.2. Informative References..................................15 83 1. Introduction 85 This document defines an application protocol for TV Band Devices 86 (TVBDs) to access Whitespace Database (WSDB) services over the 87 Internet. Providing available channel lists to TVBDs is the primary 88 service provided by the WSDB. Several operational requirements are 89 defined to support this primary function, such as device 90 registration, and FCC ID verification. The protocol allows any TVBD 91 to gain access to the services of the WSDB by communicating over 92 commonly used Internet protocols. 94 The protocol defined by this document is compliant with FCC 95 Requirements [FCC 10-174] and partially compliant with IETF PAWS 96 requirements [IETF-PAWS-03] where the FCC requirements overlap with 97 IETF PAWS requirements. 99 A primary goal of the document is to define a protocol between the 100 White Space Database and TVBDs compliant with FCC Requirements [FCC 101 10-174] and also compliant with relevant overlapping requirements 102 defined by IETF PAWS [IETF-PAWS-03]. The protocol can be easily 103 extended to include the remaining IETF PAWS requirements. 105 2. Conventions and Terminology 107 2.1. Conventions used in this document 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in RFC-2119 [RFC2119]. 113 In this document, these words will appear with that interpretation 114 only when in ALL CAPS. Lower case uses of these words are not to be 115 interpreted as carrying RFC-2119 significance. 117 In this document, the characters "{" and "}" surrounding a word 118 indicates a variable to be replaced with an appropriate value as 119 described in the documented section. 121 In this document, the characters "[" and "]" surrounding a word 122 indicates a variable to be replaced with an appropriate value as 123 described in the documented section. 125 2.2. Terminology 127 TV Band Device (TVBD, TVWSDB or WSD) 129 A White Space Device that operates in the TV bands. 131 White Space Database (WSDB) 132 In the context of white space and cognitive radio technologies, 133 the database is an entity which contains, but is not limited to, 134 current information about available spectrum at any given location 135 and other types of related (to the white space spectrum) or 136 relevant information. 138 3. Protocol Stack 140 The Application Protocol defined in this document utilizes the 141 following protocol stack for communication between the WSDB and TVBD: 143 Application Layer = HTTPS 145 Presentation Layer = SSL / XML (or JSON) 147 Session Layer = Undefined by this standard 149 Transport Layer = TCP 151 Network Layer = IP 153 Data Link Layer = Undefined by this standard 155 Physical Layer = Undefined by this standard 157 Many modern applications are successfully utilizing this protocol 158 stack for client-server communications, and most modern network 159 devices already include a TCP/IP stack. Software implementations of 160 these protocols are readily available for use in the development of 161 White Space Databases (WSDB) and Network Devices (TVBD) to support 162 the application standard defined in this document. 164 HTTPS is a key component used in this protocol, providing a commonly 165 used request-response protocol for a client-server model, where the 166 WSDB is the server and the TVBD is the client. Additionally, HTTPS 167 provides security via SSL to satisfy security requirements. 169 4. Protocol Definition 171 This section defines the application protocol that shall be used 172 between the WSDB and TVBD for all services offered by the WSDB. The 173 following sections define the services provided by the WSDB. The 174 services are accessed by the TVBD using HTTPS GET and PUT requests 175 over the Internet. Providing available Channel Lists to TVBDs is the 176 primary service provided by the WSDB. 178 Operations are only initiated by the TVBD, with a response from the 179 WSDB. This eliminates the necessity of the WSDB initiating 180 communications with the TVBD. 182 Three services are defined on the interface between the WSDB and 183 TVBD, Registration, Channel List Request, and FCC ID Verification. 184 The services are listed in a logical order representing the steps 185 that a TVBD MUST take to obtain service from the WSDB. 187 4.1. Registration 189 A fixed TVBD MUST register with the WSDB prior to operating for the 190 first time, or after changing location, or if any of the registration 191 data changes. Only fixed TVBDs register with the WSDB, 192 personal/portable TVBDs do not. 194 To successfully register, the FCC ID and Serial Number of the TVBD 195 must be enrolled at the WSDB. Device enrollment is an administration 196 function that is not in the scope of this application protocol 197 definition. WSDB operators may define their own methods for acquiring 198 and maintaining device enrollment data. 200 To register with the WSDB, the TVBD MUST send a Registration Request 201 Message to the WSDB (see section 4.1.1. ). 203 One of two possible results shall be returned by the WSDB: 205 1. Successful Registration. The Registration will be valid for RVP 206 and will be extended by subsequent WSDB access by the TVBD. 208 2. Unsuccessful Registration. The TVBD identifiers (FCC ID and Serial 209 Number) were unrecognized or unsupported by the WSDB. 211 A successful Registration Reply will be returned to the TVBD only if 212 all of the following are true: 214 - The FCC identifier and manufacturer's serial number are enrolled 215 at the WSDB 217 - The device location is within the appropriate regulatory 218 boundaries 220 - The device type is valid (only Fixed TVBDs may register), and is 221 allowed for the authorized equipment class 223 - The antenna height is less than or equal to 30 meters 224 - The HAAT of the device location calculated by the database is 225 less than or equal to 76 meters 227 A successful registration will overwrite any previous registration 228 information for the same TVBD, as identified by FCC ID and serial 229 number. 231 The WSDB will retain the TVBD registration for a fixed period (RVP) 232 with no activity. RVP will be extended by every successful 233 registration, and by any subsequent Channel List Request received 234 from the TVBD. 236 If a TVBD registration expires, Channel List Requests will fail with 237 a reason code of not registered, informing the TVBD of the need to 238 register. 240 4.1.1. Registration Request Message 242 A TVBD MUST register with the WSDB by sending an HTTP PUT message in 243 the following format: 245 HTTPS Method: PUT 247 URL: https://{HOST.DOMAIN}/{VERSION}/devices/{FCCID}/{SERIAL} 249 XML Body: 251 253 Decimal 254 String 255 String 256 String 257 String 258 String 259 String 260 String 261 String 262 String 263 Byte 264 Decimal 265 Decimal 266 268 Where: 270 {HOST.DOMAIN} is replaced with the host.domain of the WSDB. 272 {VERSION} is replaced with a valid version number defined by the 273 WSDB. 275 {FCCID} is the alphanumeric FCC identifier of the device. 277 {SERIAL} is the manufacturer-assigned alphanumeric serial number of 278 the device. 280 is the device's antenna height above ground level in 281 meters. 283 is the address city for the contact person. 285 is the country for the address of the contact 286 person. 288 is the email address for the contact person. 290 is the name of the contact person responsible for the 291 device's operation. 293 is the phone number for the contact person 295 is the state for the address of the contact person. 297 is the street address for the contact person. 299 is the zip code for the address of the contact person. 301 is the name of the individual or business that is 302 responsible for the device. 304 is the numeric device type. TODO: Define enum values! 306 is the decimal latitude of the device's geographic 307 coordinates (NAD 83) accurate to +/- 50 m. 309 is the decimal longitude of the device's geographic 310 coordinates (NAD 83) accurate to +/- 50 m. 312 4.2. Channel List Request 314 The WSDB will provide, upon request, the available TV channels at the 315 TVBD's location. 317 There are three possible outcomes to a Channel Request: 319 1. Successful, with Channel List. 321 2. Successful, with no Channels Available. 323 3. Unsuccessful 325 To successfully receive a channel list, the FCC ID and Serial Number 326 of the TVBD must be enrolled at the WSDB. 328 A successful Channel List Response will be returned to the TVBD only 329 if all of the following are true: 331 - The FCC identifier and manufacturer's serial number are 332 enrolled at the WSDB. 334 - The device location is within the appropriate regulatory 335 boundaries. 337 - The device type is valid, and allowed for the authorized 338 equipment class. 340 - For a fixed TVBD, the device is registered and the location 341 matches the values previously registered. 343 4.2.1. Channel List Request Message 345 A Fixed or Mode II TVBD needing a channel to operate on can make a 346 Channel List Request to the WSDB by sending an HTTP GET message with 347 the following format: 349 HTTPS Method: GET 351 URL: 353 https://{HOST.DOMAIN}/{VERSION}/channels/{LATITUDE}/{LONGITUDE}/?fcci 354 d={FCCID}&serial={SERIAL}&type={DEVICETYPE} 356 Where: 358 {HOST.DOMAIN} is replaced with the host.domain of the WSDB. 360 {VERSION} is replaced with a valid version number defined by the 361 WSDB. 363 {LATITUDE} is the decimal latitude of the device. 365 {LONGITUDE} is the decimal longitude of the device. 367 {FCCID} is the alphanumeric FCC identifier of the device. 369 {SERIAL} is the manufacturer-assigned alphanumeric serial number of 370 the device. 372 {DEVICETYPE} is the numeric device type and antenna configuration. 374 4.2.2. Channel List Response 376 Upon receipt of a Channel List Request from a TVDB, the WSDB will 377 return a Channel List Response to the TVDB, using the following 378 sample format: 380 HTTP/1.1 200 OK\r\n 381 Cache-Control: private\r\n 382 Content-Length: {LENGTH}\r\n 383 Content-Type: application/xml; charset=utf-8\r\n 384 WSDB-Version: 3\r\n 385 WSDB-Status: {STATUS}\r\n 386 Date: Fri, 1 Jan 2010 16:00:00 GMT\r\n 387 \r\n 388 390 integer 391 integer,...,integer 392 integer 394 Where: 396 {STATUS} provides the status for the Request, 0=valid. 398 {LENGTH} is the number of characters in the XML body. 400 is the number of channel entries in . 402 is a comma-separated list of channels, an empty list if 403 = 0, otherwise entries. 405 is the number of hours until the channel list must be 406 refreshed. 408 4.3. FCC ID Verification Request 410 The FCC ID Verification Request provides a method for TVBDs to verify 411 the validity of Mode I TVBDs that are dependent upon a master TVBD 412 for channel lists. The WSDB will respond whether a requested FCC ID 413 is valid. 415 An FCC ID Verification Response will always be returned. 417 The status returned in the WSDB response is based on whether the FCC 418 ID is found in the authorized list of FCC IDs downloaded from the FCC 419 OET EAS. 421 The following sequence of events describes the use of this request: 423 1. A Fixed or Mode II TVBD needs to verify whether a Mode I TVBD is 424 valid, and sends a FCC ID Verification Request Message to the WSDB. 426 2. The WSDB checks the FCC ID against the authorized FCC IDs and 427 returns a reason code of success (0) only if found, otherwise unknown 428 (not 0) will be returned. As long as the message is decodable, an FCC 429 ID Verification Response will always be returned. 431 4.3.1. FCC ID Verification Request Message 433 HTTPS Method: GET 435 URL: 437 https://{HOST.DOMAIN}/{VERSION}/devices/{FCCID} 439 Where: 441 {HOST.DOMAIN} is replaced with the host.domain of the WSDB. 443 {VERSION} is replaced with a valid version number defined by the 444 WSDB. 446 {FCCID} is the alphanumeric FCC identifier of the device. 448 4.3.2. FCC ID Verification Response 450 Upon receipt of a FCC ID Verification Request from a TVDB, the WSDB 451 will return a status code, using the following sample format: 453 HTTP/1.1 200 OK\r\n 454 Cache-Control: private\r\n 455 WSDB-Version: 3\r\n 456 WSDB-Status: {STATUS}\r\n 457 Date: Fri, 1 Jan 2010 16:00:00 GMT\r\n 458 Content-Length: 0\r\n 459 \r\n 461 Where: 463 {STATUS} provides the status for the Request, 0=valid. 465 4.4. Data Objects 467 This section defines the data objects used in this protocol. 469 Legend: 470 Object Name | XML Field Name | Type | 471 - Description and Valid Values 473 antenna height | AntennaHeight | float | 474 - Antenna height above ground level in meters, ignored for 475 personal/portable TVBDs 477 channel | ChannelList | integer list | 478 - Comma-separated list of available TV channel numbers, 479 an empty list if ChannelCount=0, otherwise ChannelCount entries 480 Valid values: 2, 5-20, 21-36, 37-51 482 channel list count | ChannelCount | integer | 483 - Number of TV channel numbers in the list 484 0=no channels available 485 >0= number of TV channel numbers in ChannelList 487 contact email | ContactEmail | string(100) | 488 - email address for the contact person 490 contact name | ContactName | string(100) | 491 - name of a contact person responsible for the device's operation 493 contact phone | ContactPhone | string(50) | 494 - phone number for the contact person 496 contact street address | ContactStreet | string(100) | 497 - street address for the contact person 499 contact city | ContactCity | string(50) | 500 - city for the address for the contact person 502 contact state | ContactState | string(2) | 503 - state for the address for the contact person 505 contact postal code| ContactZip | string(20) | 506 - postal code for the address for the contact person 508 contact country | ContactCountry | string(2) | 509 - country for the address for the contact person 511 country code | CountryCode | string(2) | 512 - 2-character ISO 3166 country code, used to enforce the 513 regulatory domain 515 device latitude | Latitude | float | 516 - decimal latitude of device's geographic coordinates (NAD 83) 517 accurate to +/ 50 m 519 device longitude | Longitude | float | 520 - decimal longitude of device's geographic coordinates (NAD 83) 521 accurate to +/ 50 m 523 device type | DeviceType | integer | 524 - Numeric TVBD type, used for applying channel availability and 525 separation rules. 527 0=reserved 528 1=40 mW Mode I personal/portable (not used) 529 2=100 mW Mode I personal/portable (not used) 530 3=40 mW Mode II personal/portable 531 4=100 mW Mode II personal/portable 532 5=reserved 533 6=reserved 534 7=reserved 535 8=Fixed 537 FCC ID | FCCID | string(17) | 538 - alphanumeric FCC identifier of the TVBD 540 owner name | DeviceOwner | string(50) | 541 - name of the individual or business that is responsible for the 542 device 544 serial number | Serial | string(32) | 545 - alphanumeric manufacturer's serial number for the TVBD 547 status | WSDB-Status: (HTTP header) | integer | 548 - Status result for the request, see section 4.6. for status code 549 values. 551 Strings longer than the maximum string length specified in the Type 552 column will be truncated to the maximum string length. 554 4.5. Timers 556 The following timers are used by the protocol during operation. 558 Legend: 559 Timer Name (Default Value): Description 561 CLRP (1440 minutes): Channel List Refresh Period. The channel list 562 must be refreshed at least once per day. 564 CLTO (n/a minutes): Channel List Timeout. If the channel list cannot 565 be refreshed, it times out "tomorrow" at 11:59 pm, local time, 566 relative to when the channel list was originally provided. 568 CRRP (60 minutes): Channel List Retry Period. If the WSDB returns No 569 Channels Available, the period the TVBD should wait before retrying 570 the request, to prevent overloading the WSDB with requests. 572 CRT (5 seconds): Channel list Request Timer. Deadman timeout for no 573 response to Channel List Request. 575 FVRT (5 seconds): FCC ID Verification Request Timer. Deadman timeout 576 for no response to Channel List Request. 578 RVP (90 days): Registration Valid Period. The WSDB will retain a 579 TVBD registration for this period with no activity. This period is 580 extended for each successful Registration Request and every Channel 581 List Request. 583 RRRP (60 minutes): Registration Request Retry Period. If the 584 registration request fails, the period the TVBD should wait before 585 retrying the request, to prevent overloading the WSDB. 587 RRT (5 seconds): Registration Request Timer. Deadman timeout for no 588 response to Registration Request. 590 4.6. Status Return Codes 592 The following status return codes are provided by the WSDB on 593 responses to the TVBD to communicate the status of requests made by 594 the TVDB. 596 Legend: 597 Status Code, Description, Returned Text 599 0, "Successful", Success 600 1, "Malformed Request", MalformedRequest 601 2, "FCC ID is not supported", FccIdNotSupported 602 3, "Reserved", Reserverd 603 4, "Device has not registered", DeviceNotRegistered 604 5, "FCC has disallowed channels", FccDesignatedNoChannels 605 6, "Unknown Country Code", UnknownCountryCode 606 7, "Device is not enrolled", NotEnrolled 607 8, "Device is not enrolled in specified country", 608 NotEnrolledInCountry 609 9, "Location is outside the regulatory domain", 610 LocatedOutsideRegulatoryDomain 611 10, "Antenna Height cannot be above 30 meters", 612 AntennaHeightAbove30m 613 11, "Height Above Average Terrain cannot be above 76 meters", 614 HaatAbove76m 615 12, "FCC ID is invalid", InvalidFccId 616 13, "Device Type is invalid", UnknownDeviceType 618 14, "Request does not match previous registration", 619 RequestDoesNotMatchRegistration 620 15, "Device Type does not match the equipment class", 621 DeviceTypeDoesNotMatchEquipmentClass 622 255, "No Value", None 623 254, "Unknown Error", UnknownError 625 5. Formal Syntax 627 While this specification uses an XML message structure, JSON may 628 provide an acceptable option for encoding messages. 630 6. IANA Considerations 632 None 634 7. Security Considerations 636 In the protocol defined in this document, the use of HTTPS is 637 essential for satisfying FCC and IETF-PAWS security requirements 638 related to message integrity. 640 8. Conclusions 642 This document defines an application protocol for WSDB services 643 provided to TVBDs. The protocol complies with FCC Rules/Requirements 644 [FCC 10-174] and in the context of operating an FCC certified 645 database, it also complies with requirements defined by IETF PAWS. We 646 believe this protocol can be easily extended to include the remaining 647 requirements not already satisfied from the IETF PAWS requirements. 649 9. Acknowledgments 651 This document was prepared using 2-Word-v2.0.template.dot. 653 10. References 655 10.1. Normative References 657 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 658 Requirement Levels", BCP 14, RFC 2119, March 1997. 660 10.2. Informative References 662 [FCC 10-174] 663 Second Memorandum Opinion and Order, FCC 10-174, September, 664 2010 665 http://hraunfoss.fcc.gov/edocs_public/attachmatch/FCC-10- 666 174A1.pdf 668 [IETF-PAWS-03] 669 Probasco, S., Bajko, Ed., Patil, B., "Protocol to Access 670 White Space database: PS, use cases and rqmts", draft-ietf- 671 paws-problem-stmt-usecases-rqmts-03, February 2012 673 Authors' Addresses 675 Donald Joslyn 676 Spectrum Bridge, Inc. 677 1064 Greenwood Blvd. Suite 200 678 Lake Mary, FL 32746 679 Email: d.joslyn@spectrumbridge.com 681 Robin Roberts 682 Spectrum Bridge, Inc. 683 1064 Greenwood Blvd. Suite 200 684 Lake Mary, FL 32746 685 Email: r.roberts@spectrumbridge.com