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]
