Internet DRAFT - draft-sbi-paws-protocol

draft-sbi-paws-protocol



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:

   <RegistrationRequest
   xmlns="http://schemas.datacontract.org/2004/07/{NAMESPACE}">
     <AntennaHeight>Decimal</AntennaHeight>
     <ContactCity>String</ContactCity>
     <ContactCountry>String</ContactCountry>
     <ContactEmail>String</ContactEmail>
     <ContactName>String</ContactName>
     <ContactPhone>String</ContactPhone>
     <ContactState>String</ContactState>
     <ContactStreet>String</ContactStreet>
     <ContactZip>String</ContactZip>
     <DeviceOwner>String</DeviceOwner>
     <DeviceType>Byte</DeviceType>
     <Latitude>Decimal</Latitude>
     <Longitude>Decimal</Longitude>
   </RegistrationRequest>

   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.

   <AntennaHeight> is the device's antenna height above ground level in
   meters.

   <ContactCity> is the address city for the contact person.

   <ContactCountry> is the country for the address of the contact
   person.

   <ContactEmail> is the email address for the contact person.

   <ContactName> is the name of the contact person responsible for the
   device's operation.

   <ContactPhone> is the phone number for the contact person

   <ContactState> is the state for the address of the contact person.

   <ContactState> is the street address for the contact person.

   <ContactZip> is the zip code for the address of the contact person.

   <DeviceOwner> is the name of the individual or business that is
   responsible for the device.

   <DeviceType> is the numeric device type. TODO: Define enum values!

   <Latitude> is the decimal latitude of the device's geographic
   coordinates (NAD 83) accurate to +/- 50 m.

   <Longitude> 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
     <ChannelResponse
     xmlns="http://schemas.datacontract.org/2004/07/{NAMESPACE}">
     <ChannelCount>integer</ChannelCount>
     <ChannelList>integer,...,integer</ChannelList>
     <RefreshIn>integer</RefreshIn>

   Where:

   {STATUS} provides the status for the Request, 0=valid.

   {LENGTH} is the number of characters in the XML body.

   <ChannelCount> is the number of channel entries in <ChannelList>.

   <ChannelList> is a comma-separated list of channels, an empty list if
   <ChannelCount> = 0, otherwise <ChannelCount> entries.

   <RefreshIn> 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]