Applications Area Working Group D. Joslyn Internet Draft R. Roberts Intended status: Standards Track Spectrum Bridge, Inc. Expires: September 2012 March 5, 2012 Protocol for Communication between White Space Device and White Space Database draft-sbi-paws-protocol-00.txt Status of this Memo This Internet-Draft is submitted 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 5, 2012. Copyright Notice Copyright (c) 2012 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. Joslyn & Roberts Expires September 5, 2012 [Page 1] Internet-Draft TVBD to WSDB Protocol March 2012 Abstract This document defines an application protocol for WSDB services provided to TV Band Devices (TVBDs). The protocol complies with FCC Rules/Requirements [FCC 10-174] and in the context of operating an FCC certified database, it also complies with requirements defined by IETF PAWS [IETF-PAWS-03]. We believe this protocol can be easily extended to include the remaining requirements not already satisfied from the IETF PAWS requirements. Table of Contents 1. Introduction...................................................2 2. Conventions and Terminology....................................3 2.1. Conventions used in this document.........................3 2.2. Terminology...............................................3 3. Protocol Stack.................................................4 4. Protocol Definition............................................4 4.1. Registration..............................................5 4.1.1. Registration Request Message.........................6 4.2. Channel List Request......................................7 4.2.1. Channel List Request Message.........................8 4.2.2. Channel List Response................................9 4.3. FCC ID Verification Request..............................10 4.3.1. FCC ID Verification Request Message.................10 4.3.2. FCC ID Verification Response........................11 4.4. Data Objects.............................................11 4.5. Timers...................................................13 4.6. Status Return Codes......................................14 5. Formal Syntax.................................................15 6. IANA Considerations...........................................15 7. Security Considerations.......................................15 8. Conclusions...................................................15 9. Acknowledgments...............................................15 10. References...................................................15 10.1. Normative References....................................15 10.2. Informative References..................................15 1. Introduction This document defines an application protocol for TV Band Devices (TVBDs) to access Whitespace Database (WSDB) services over the Internet. Providing available channel lists to TVBDs is the primary service provided by the WSDB. Several operational requirements are Joslyn & Roberts Expires September 5, 2012 [Page 2] Internet-Draft TVBD to WSDB Protocol March 2012 defined to support this primary function, such as device registration, and FCC ID verification. The protocol allows any TVBD to gain access to the services of the WSDB by communicating over commonly used Internet protocols. The protocol defined by this document is compliant with FCC Requirements [FCC 10-174] and partially compliant with IETF PAWS requirements [IETF-PAWS-03] where the FCC requirements overlap with IETF PAWS requirements. A primary goal of the document is to define a protocol between the White Space Database and TVBDs compliant with FCC Requirements [FCC 10-174] and also compliant with relevant overlapping requirements defined by IETF PAWS [IETF-PAWS-03]. The protocol can be easily extended to include the remaining IETF PAWS requirements. 2. Conventions and Terminology 2.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 RFC-2119 [RFC2119]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying RFC-2119 significance. In this document, the characters "{" and "}" surrounding a word indicates a variable to be replaced with an appropriate value as described in the documented section. In this document, the characters "[" and "]" surrounding a word indicates a variable to be replaced with an appropriate value as described in the documented section. 2.2. Terminology TV Band Device (TVBD, TVWSDB or WSD) A White Space Device that operates in the TV bands. White Space Database (WSDB) Joslyn & Roberts Expires September 5, 2012 [Page 3] Internet-Draft TVBD to WSDB Protocol March 2012 In the context of white space and cognitive radio technologies, the database is an entity which contains, but is not limited to, current information about available spectrum at any given location and other types of related (to the white space spectrum) or relevant information. 3. Protocol Stack The Application Protocol defined in this document utilizes the following protocol stack for communication between the WSDB and TVBD: Application Layer = HTTPS Presentation Layer = SSL / XML (or JSON) Session Layer = Undefined by this standard Transport Layer = TCP Network Layer = IP Data Link Layer = Undefined by this standard Physical Layer = Undefined by this standard Many modern applications are successfully utilizing this protocol stack for client-server communications, and most modern network devices already include a TCP/IP stack. Software implementations of these protocols are readily available for use in the development of White Space Databases (WSDB) and Network Devices (TVBD) to support the application standard defined in this document. HTTPS is a key component used in this protocol, providing a commonly used request-response protocol for a client-server model, where the WSDB is the server and the TVBD is the client. Additionally, HTTPS provides security via SSL to satisfy security requirements. 4. Protocol Definition This section defines the application protocol that shall be used between the WSDB and TVBD for all services offered by the WSDB. The following sections define the services provided by the WSDB. The services are accessed by the TVBD using HTTPS GET and PUT requests over the Internet. Providing available Channel Lists to TVBDs is the primary service provided by the WSDB. Joslyn & Roberts Expires September 5, 2012 [Page 4] Internet-Draft TVBD to WSDB Protocol March 2012 Operations are only initiated by the TVBD, with a response from the WSDB. This eliminates the necessity of the WSDB initiating communications with the TVBD. Three services are defined on the interface between the WSDB and TVBD, Registration, Channel List Request, and FCC ID Verification. The services are listed in a logical order representing the steps that a TVBD MUST take to obtain service from the WSDB. 4.1. Registration A fixed TVBD MUST register with the WSDB prior to operating for the first time, or after changing location, or if any of the registration data changes. Only fixed TVBDs register with the WSDB, personal/portable TVBDs do not. To successfully register, the FCC ID and Serial Number of the TVBD must be enrolled at the WSDB. Device enrollment is an administration function that is not in the scope of this application protocol definition. WSDB operators may define their own methods for acquiring and maintaining device enrollment data. To register with the WSDB, the TVBD MUST send a Registration Request Message to the WSDB (see section 4.1.1. ). One of two possible results shall be returned by the WSDB: 1. Successful Registration. The Registration will be valid for RVP and will be extended by subsequent WSDB access by the TVBD. 2. Unsuccessful Registration. The TVBD identifiers (FCC ID and Serial Number) were unrecognized or unsupported by the WSDB. A successful Registration Reply will be returned to the TVBD only if all of the following are true: - The FCC identifier and manufacturer's serial number are enrolled at the WSDB - The device location is within the appropriate regulatory boundaries - The device type is valid (only Fixed TVBDs may register), and is allowed for the authorized equipment class - The antenna height is less than or equal to 30 meters Joslyn & Roberts Expires September 5, 2012 [Page 5] Internet-Draft TVBD to WSDB Protocol March 2012 - The HAAT of the device location calculated by the database is less than or equal to 76 meters A successful registration will overwrite any previous registration information for the same TVBD, as identified by FCC ID and serial number. The WSDB will retain the TVBD registration for a fixed period (RVP) with no activity. RVP will be extended by every successful registration, and by any subsequent Channel List Request received from the TVBD. If a TVBD registration expires, Channel List Requests will fail with a reason code of not registered, informing the TVBD of the need to register. 4.1.1. Registration Request Message A TVBD MUST register with the WSDB by sending an HTTP PUT message in the following format: HTTPS Method: PUT URL: https://{HOST.DOMAIN}/{VERSION}/devices/{FCCID}/{SERIAL} XML Body: Decimal String String String String String String String String String Byte Decimal Decimal Where: Joslyn & Roberts Expires September 5, 2012 [Page 6] Internet-Draft TVBD to WSDB Protocol March 2012 {HOST.DOMAIN} is replaced with the host.domain of the WSDB. {VERSION} is replaced with a valid version number defined by the WSDB. {FCCID} is the alphanumeric FCC identifier of the device. {SERIAL} is the manufacturer-assigned alphanumeric serial number of the device. is the device's antenna height above ground level in meters. is the address city for the contact person. is the country for the address of the contact person. is the email address for the contact person. is the name of the contact person responsible for the device's operation. is the phone number for the contact person is the state for the address of the contact person. is the street address for the contact person. is the zip code for the address of the contact person. is the name of the individual or business that is responsible for the device. is the numeric device type. TODO: Define enum values! is the decimal latitude of the device's geographic coordinates (NAD 83) accurate to +/- 50 m. is the decimal longitude of the device's geographic coordinates (NAD 83) accurate to +/- 50 m. 4.2. Channel List Request The WSDB will provide, upon request, the available TV channels at the TVBD's location. Joslyn & Roberts Expires September 5, 2012 [Page 7] Internet-Draft TVBD to WSDB Protocol March 2012 There are three possible outcomes to a Channel Request: 1. Successful, with Channel List. 2. Successful, with no Channels Available. 3. Unsuccessful To successfully receive a channel list, the FCC ID and Serial Number of the TVBD must be enrolled at the WSDB. A successful Channel List Response will be returned to the TVBD only if all of the following are true: - The FCC identifier and manufacturer's serial number are enrolled at the WSDB. - The device location is within the appropriate regulatory boundaries. - The device type is valid, and allowed for the authorized equipment class. - For a fixed TVBD, the device is registered and the location matches the values previously registered. 4.2.1. Channel List Request Message A Fixed or Mode II TVBD needing a channel to operate on can make a Channel List Request to the WSDB by sending an HTTP GET message with the following format: HTTPS Method: GET URL: https://{HOST.DOMAIN}/{VERSION}/channels/{LATITUDE}/{LONGITUDE}/?fcci d={FCCID}&serial={SERIAL}&type={DEVICETYPE} Where: {HOST.DOMAIN} is replaced with the host.domain of the WSDB. {VERSION} is replaced with a valid version number defined by the WSDB. Joslyn & Roberts Expires September 5, 2012 [Page 8] Internet-Draft TVBD to WSDB Protocol March 2012 {LATITUDE} is the decimal latitude of the device. {LONGITUDE} is the decimal longitude of the device. {FCCID} is the alphanumeric FCC identifier of the device. {SERIAL} is the manufacturer-assigned alphanumeric serial number of the device. {DEVICETYPE} is the numeric device type and antenna configuration. 4.2.2. Channel List Response Upon receipt of a Channel List Request from a TVDB, the WSDB will return a Channel List Response to the TVDB, using the following sample format: HTTP/1.1 200 OK\r\n Cache-Control: private\r\n Content-Length: {LENGTH}\r\n Content-Type: application/xml; charset=utf-8\r\n WSDB-Version: 3\r\n WSDB-Status: {STATUS}\r\n Date: Fri, 1 Jan 2010 16:00:00 GMT\r\n \r\n integer integer,...,integer integer Where: {STATUS} provides the status for the Request, 0=valid. {LENGTH} is the number of characters in the XML body. is the number of channel entries in . is a comma-separated list of channels, an empty list if = 0, otherwise entries. is the number of hours until the channel list must be refreshed. Joslyn & Roberts Expires September 5, 2012 [Page 9] Internet-Draft TVBD to WSDB Protocol March 2012 4.3. FCC ID Verification Request The FCC ID Verification Request provides a method for TVBDs to verify the validity of Mode I TVBDs that are dependent upon a master TVBD for channel lists. The WSDB will respond whether a requested FCC ID is valid. An FCC ID Verification Response will always be returned. The status returned in the WSDB response is based on whether the FCC ID is found in the authorized list of FCC IDs downloaded from the FCC OET EAS. The following sequence of events describes the use of this request: 1. A Fixed or Mode II TVBD needs to verify whether a Mode I TVBD is valid, and sends a FCC ID Verification Request Message to the WSDB. 2. The WSDB checks the FCC ID against the authorized FCC IDs and returns a reason code of success (0) only if found, otherwise unknown (not 0) will be returned. As long as the message is decodable, an FCC ID Verification Response will always be returned. 4.3.1. FCC ID Verification Request Message HTTPS Method: GET URL: https://{HOST.DOMAIN}/{VERSION}/devices/{FCCID} Where: {HOST.DOMAIN} is replaced with the host.domain of the WSDB. {VERSION} is replaced with a valid version number defined by the WSDB. {FCCID} is the alphanumeric FCC identifier of the device. Joslyn & Roberts Expires September 5, 2012 [Page 10] Internet-Draft TVBD to WSDB Protocol March 2012 4.3.2. FCC ID Verification Response Upon receipt of a FCC ID Verification Request from a TVDB, the WSDB will return a status code, using the following sample format: HTTP/1.1 200 OK\r\n Cache-Control: private\r\n WSDB-Version: 3\r\n WSDB-Status: {STATUS}\r\n Date: Fri, 1 Jan 2010 16:00:00 GMT\r\n Content-Length: 0\r\n \r\n Where: {STATUS} provides the status for the Request, 0=valid. 4.4. Data Objects This section defines the data objects used in this protocol. Legend: Object Name | XML Field Name | Type | - Description and Valid Values antenna height | AntennaHeight | float | - Antenna height above ground level in meters, ignored for personal/portable TVBDs channel | ChannelList | integer list | - Comma-separated list of available TV channel numbers, an empty list if ChannelCount=0, otherwise ChannelCount entries Valid values: 2, 5-20, 21-36, 37-51 channel list count | ChannelCount | integer | - Number of TV channel numbers in the list 0=no channels available >0= number of TV channel numbers in ChannelList contact email | ContactEmail | string(100) | - email address for the contact person contact name | ContactName | string(100) | Joslyn & Roberts Expires September 5, 2012 [Page 11] Internet-Draft TVBD to WSDB Protocol March 2012 - name of a contact person responsible for the device's operation contact phone | ContactPhone | string(50) | - phone number for the contact person contact street address | ContactStreet | string(100) | - street address for the contact person contact city | ContactCity | string(50) | - city for the address for the contact person contact state | ContactState | string(2) | - state for the address for the contact person contact postal code| ContactZip | string(20) | - postal code for the address for the contact person contact country | ContactCountry | string(2) | - country for the address for the contact person country code | CountryCode | string(2) | - 2-character ISO 3166 country code, used to enforce the regulatory domain device latitude | Latitude | float | - decimal latitude of device's geographic coordinates (NAD 83) accurate to +/ 50 m device longitude | Longitude | float | - decimal longitude of device's geographic coordinates (NAD 83) accurate to +/ 50 m device type | DeviceType | integer | - Numeric TVBD type, used for applying channel availability and separation rules. 0=reserved 1=40 mW Mode I personal/portable (not used) 2=100 mW Mode I personal/portable (not used) 3=40 mW Mode II personal/portable 4=100 mW Mode II personal/portable Joslyn & Roberts Expires September 5, 2012 [Page 12] Internet-Draft TVBD to WSDB Protocol March 2012 5=reserved 6=reserved 7=reserved 8=Fixed FCC ID | FCCID | string(17) | - alphanumeric FCC identifier of the TVBD owner name | DeviceOwner | string(50) | - name of the individual or business that is responsible for the device serial number | Serial | string(32) | - alphanumeric manufacturer's serial number for the TVBD status | WSDB-Status: (HTTP header) | integer | - Status result for the request, see section 4.6. for status code values. Strings longer than the maximum string length specified in the Type column will be truncated to the maximum string length. 4.5. Timers The following timers are used by the protocol during operation. Legend: Timer Name (Default Value): Description CLRP (1440 minutes): Channel List Refresh Period. The channel list must be refreshed at least once per day. CLTO (n/a minutes): Channel List Timeout. If the channel list cannot be refreshed, it times out "tomorrow" at 11:59 pm, local time, relative to when the channel list was originally provided. CRRP (60 minutes): Channel List Retry Period. If the WSDB returns No Channels Available, the period the TVBD should wait before retrying the request, to prevent overloading the WSDB with requests. CRT (5 seconds): Channel list Request Timer. Deadman timeout for no response to Channel List Request. FVRT (5 seconds): FCC ID Verification Request Timer. Deadman timeout for no response to Channel List Request. Joslyn & Roberts Expires September 5, 2012 [Page 13] Internet-Draft TVBD to WSDB Protocol March 2012 RVP (90 days): Registration Valid Period. The WSDB will retain a TVBD registration for this period with no activity. This period is extended for each successful Registration Request and every Channel List Request. RRRP (60 minutes): Registration Request Retry Period. If the registration request fails, the period the TVBD should wait before retrying the request, to prevent overloading the WSDB. RRT (5 seconds): Registration Request Timer. Deadman timeout for no response to Registration Request. 4.6. Status Return Codes The following status return codes are provided by the WSDB on responses to the TVBD to communicate the status of requests made by the TVDB. Legend: Status Code, Description, Returned Text 0, "Successful", Success 1, "Malformed Request", MalformedRequest 2, "FCC ID is not supported", FccIdNotSupported 3, "Reserved", Reserverd 4, "Device has not registered", DeviceNotRegistered 5, "FCC has disallowed channels", FccDesignatedNoChannels 6, "Unknown Country Code", UnknownCountryCode 7, "Device is not enrolled", NotEnrolled 8, "Device is not enrolled in specified country", NotEnrolledInCountry 9, "Location is outside the regulatory domain", LocatedOutsideRegulatoryDomain 10, "Antenna Height cannot be above 30 meters", AntennaHeightAbove30m 11, "Height Above Average Terrain cannot be above 76 meters", HaatAbove76m 12, "FCC ID is invalid", InvalidFccId 13, "Device Type is invalid", UnknownDeviceType 14, "Request does not match previous registration", RequestDoesNotMatchRegistration 15, "Device Type does not match the equipment class", DeviceTypeDoesNotMatchEquipmentClass 255, "No Value", None 254, "Unknown Error", UnknownError Joslyn & Roberts Expires September 5, 2012 [Page 14] Internet-Draft TVBD to WSDB Protocol March 2012 5. Formal Syntax While this specification uses an XML message structure, JSON may provide an acceptable option for encoding messages. 6. IANA Considerations None 7. Security Considerations In the protocol defined in this document, the use of HTTPS is essential for satisfying FCC and IETF-PAWS security requirements related to message integrity. 8. Conclusions This document defines an application protocol for WSDB services provided to TVBDs. The protocol complies with FCC Rules/Requirements [FCC 10-174] and in the context of operating an FCC certified database, it also complies with requirements defined by IETF PAWS. We believe this protocol can be easily extended to include the remaining requirements not already satisfied from the IETF PAWS requirements. 9. Acknowledgments This document was prepared using 2-Word-v2.0.template.dot. 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 10.2. Informative References [FCC 10-174] Second Memorandum Opinion and Order, FCC 10-174, September, 2010 http://hraunfoss.fcc.gov/edocs_public/attachmatch/FCC-10- 174A1.pdf [IETF-PAWS-03] Probasco, S., Bajko, Ed., Patil, B., "Protocol to Access White Space database: PS, use cases and rqmts", draft-ietf- paws-problem-stmt-usecases-rqmts-03, February 2012 Joslyn & Roberts Expires September 5, 2012 [Page 15] Internet-Draft TVBD to WSDB Protocol March 2012 Authors' Addresses Donald Joslyn Spectrum Bridge, Inc. 1064 Greenwood Blvd. Suite 200 Lake Mary, FL 32746 Email: d.joslyn@spectrumbridge.com Robin Roberts Spectrum Bridge, Inc. 1064 Greenwood Blvd. Suite 200 Lake Mary, FL 32746 Email: r.roberts@spectrumbridge.com Joslyn & Roberts Expires September 5, 2012 [Page 16]