draft-ietf-paws-protocol-01.txt   draft-ietf-paws-protocol-02.txt 
PAWS V. Chen, Ed. PAWS V. Chen, Ed.
Internet-Draft Google Internet-Draft Google
Intended status: Standards Track S. Das Intended status: Standards Track S. Das
Expires: June 21, 2013 Applied Communication Sciences Expires: August 16, 2013 Applied Communication Sciences
Z. Lei L. Zhu
Huawei Huawei
J. Malyar J. Malyar
Telcordia Technologies Inc. Telcordia Technologies Inc.
P. McCann P. McCann
Huawei Huawei
December 18, 2012 February 12, 2013
Protocol to Access Spectrum Database Protocol to Access Spectrum Database
draft-ietf-paws-protocol-01 draft-ietf-paws-protocol-02
Abstract Abstract
Portions of the radio spectrum that are allocated to licensees are Portions of the radio spectrum that are allocated to licensees are
available for non-interfering use. This available spectrum is called available for non-interfering use. This available spectrum is called
"White Space." Allowing secondary users access to available spectrum "White Space." Allowing secondary users access to available spectrum
"unlocks" existing spectrum to maximize its utilization and to "unlocks" existing spectrum to maximize its utilization and to
provide opportunities for innovation, resulting in greater overall provide opportunities for innovation, resulting in greater overall
spectrum utilization. spectrum utilization.
skipping to change at page 1, line 48 skipping to change at page 1, line 48
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 21, 2013. This Internet-Draft will expire on August 16, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5
2.1. Conventions Used in This Document . . . . . . . . . . . . 5 2.1. Conventions Used in This Document . . . . . . . . . . . . 5
2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Multi-ruleset Support . . . . . . . . . . . . . . . . . . 7
4. Protocol Functionalities . . . . . . . . . . . . . . . . . . . 7 4. Protocol Functionalities . . . . . . . . . . . . . . . . . . . 7
4.1. Database Discovery . . . . . . . . . . . . . . . . . . . . 7 4.1. Database Discovery . . . . . . . . . . . . . . . . . . . . 8
4.2. Initialization . . . . . . . . . . . . . . . . . . . . . . 7 4.2. Initialization . . . . . . . . . . . . . . . . . . . . . . 8
4.2.1. INIT_REQ . . . . . . . . . . . . . . . . . . . . . . . 8 4.2.1. INIT_REQ . . . . . . . . . . . . . . . . . . . . . . . 9
4.2.2. INIT_RESP . . . . . . . . . . . . . . . . . . . . . . 9 4.2.2. INIT_RESP . . . . . . . . . . . . . . . . . . . . . . 9
4.3. Device Registration . . . . . . . . . . . . . . . . . . . 9 4.3. Device Registration . . . . . . . . . . . . . . . . . . . 10
4.3.1. REGISTRATION_REQ . . . . . . . . . . . . . . . . . . . 10 4.3.1. REGISTRATION_REQ . . . . . . . . . . . . . . . . . . . 11
4.3.2. REGISTRATION_RESP . . . . . . . . . . . . . . . . . . 10 4.3.2. REGISTRATION_RESP . . . . . . . . . . . . . . . . . . 11
4.4. Available Spectrum Query . . . . . . . . . . . . . . . . . 11 4.4. Available Spectrum Query . . . . . . . . . . . . . . . . . 12
4.4.1. AVAIL_SPECTRUM_REQ . . . . . . . . . . . . . . . . . . 13 4.4.1. AVAIL_SPECTRUM_REQ . . . . . . . . . . . . . . . . . . 14
4.4.2. AVAIL_SPECTRUM_RESP . . . . . . . . . . . . . . . . . 14 4.4.2. AVAIL_SPECTRUM_RESP . . . . . . . . . . . . . . . . . 15
4.4.3. AVAIL_SPECTRUM_BATCH_REQ . . . . . . . . . . . . . . . 15 4.4.3. AVAIL_SPECTRUM_BATCH_REQ . . . . . . . . . . . . . . . 17
4.4.4. AVAIL_SPECTRUM_BATCH_RESP . . . . . . . . . . . . . . 16 4.4.4. AVAIL_SPECTRUM_BATCH_RESP . . . . . . . . . . . . . . 18
4.4.5. SPECTRUM_USE_NOTIFY . . . . . . . . . . . . . . . . . 17 4.4.5. SPECTRUM_USE_NOTIFY . . . . . . . . . . . . . . . . . 19
4.4.6. SPECTRUM_USE_RESP . . . . . . . . . . . . . . . . . . 18 4.4.6. SPECTRUM_USE_RESP . . . . . . . . . . . . . . . . . . 20
4.5. Device Validation . . . . . . . . . . . . . . . . . . . . 19 4.5. Device Validation . . . . . . . . . . . . . . . . . . . . 20
4.5.1. DEV_VALID_REQ . . . . . . . . . . . . . . . . . . . . 20 4.5.1. DEV_VALID_REQ . . . . . . . . . . . . . . . . . . . . 21
4.5.2. DEV_VALID_RESP . . . . . . . . . . . . . . . . . . . . 20 4.5.2. DEV_VALID_RESP . . . . . . . . . . . . . . . . . . . . 22
5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 20 5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 22
5.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . . . 21 5.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . . . 22
5.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . . . 22 5.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . . . 24
5.3. AntennaCharacteristics . . . . . . . . . . . . . . . . . . 23 5.3. AntennaCharacteristics . . . . . . . . . . . . . . . . . . 25
5.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . . . 24 5.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . . . 26
5.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . . . 24 5.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . . . 26
5.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . . . 25 5.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . . . 27
5.7. Spectrum . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.7. Spectrum . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.8. FrequencyRange . . . . . . . . . . . . . . . . . . . . . . 27 5.8. FrequencyRange . . . . . . . . . . . . . . . . . . . . . . 28
5.9. EventTime . . . . . . . . . . . . . . . . . . . . . . . . 28 5.9. EventTime . . . . . . . . . . . . . . . . . . . . . . . . 29
5.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . . . 28 5.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . . . 29
5.11. GeoSpectrumSchedule . . . . . . . . . . . . . . . . . . . 29 5.11. GeoSpectrumSchedule . . . . . . . . . . . . . . . . . . . 30
5.12. DeviceValidity . . . . . . . . . . . . . . . . . . . . . . 29 5.12. DeviceValidity . . . . . . . . . . . . . . . . . . . . . . 30
5.13. Error Element . . . . . . . . . . . . . . . . . . . . . . 30 5.13. Error Element . . . . . . . . . . . . . . . . . . . . . . 31
5.13.1. REQUIRED Error . . . . . . . . . . . . . . . . . . . . 31 5.13.1. REQUIRED Error . . . . . . . . . . . . . . . . . . . . 32
6. Message Encoding . . . . . . . . . . . . . . . . . . . . . . . 31 6. Message Encoding . . . . . . . . . . . . . . . . . . . . . . . 33
6.1. JSON-RPC Binding . . . . . . . . . . . . . . . . . . . . . 32 6.1. JSON-RPC Binding . . . . . . . . . . . . . . . . . . . . . 33
6.2. init Method . . . . . . . . . . . . . . . . . . . . . . . 33 6.2. init Method . . . . . . . . . . . . . . . . . . . . . . . 34
6.2.1. INIT_REQ Schema . . . . . . . . . . . . . . . . . . . 33 6.2.1. INIT_REQ Parameters . . . . . . . . . . . . . . . . . 34
6.2.2. INIT_RESP Parameters . . . . . . . . . . . . . . . . . 34 6.2.2. INIT_RESP Parameters . . . . . . . . . . . . . . . . . 36
6.3. register Method . . . . . . . . . . . . . . . . . . . . . 35 6.3. register Method . . . . . . . . . . . . . . . . . . . . . 36
6.3.1. REGISTRATION_REQ Parameters . . . . . . . . . . . . . 35 6.3.1. REGISTRATION_REQ Parameters . . . . . . . . . . . . . 36
6.3.2. REGISTRATION_RESP Parameters . . . . . . . . . . . . . 37 6.3.2. REGISTRATION_RESP Parameters . . . . . . . . . . . . . 38
6.4. getSpectrum Method . . . . . . . . . . . . . . . . . . . . 38 6.4. getSpectrum Method . . . . . . . . . . . . . . . . . . . . 39
6.4.1. AVAILABLE_SPECTRUM_REQ Parameters . . . . . . . . . . 38 6.4.1. AVAILABLE_SPECTRUM_REQ Parameters . . . . . . . . . . 39
6.4.2. AVAIL_SPECTRUM_RESP Parameters . . . . . . . . . . . . 40 6.4.2. AVAIL_SPECTRUM_RESP Parameters . . . . . . . . . . . . 41
6.5. getSpectrumBatch Method . . . . . . . . . . . . . . . . . 43 6.5. getSpectrumBatch Method . . . . . . . . . . . . . . . . . 44
6.5.1. AVAIL_SPECTRUM_BATCH_REQ Parameters . . . . . . . . . 43 6.5.1. AVAIL_SPECTRUM_BATCH_REQ Parameters . . . . . . . . . 44
6.5.2. AVAIL_SPECTRUM_BATCH_RESP Parameters . . . . . . . . . 45 6.5.2. AVAIL_SPECTRUM_BATCH_RESP Parameters . . . . . . . . . 46
6.6. notifySpectrumUse Method . . . . . . . . . . . . . . . . . 48 6.6. notifySpectrumUse Method . . . . . . . . . . . . . . . . . 49
6.6.1. SPECTRUM_USE_NOTIFY Parameters . . . . . . . . . . . . 48 6.6.1. SPECTRUM_USE_NOTIFY Parameters . . . . . . . . . . . . 49
6.6.2. SPECTRUM_USE_RESP Parameters . . . . . . . . . . . . . 50 6.6.2. SPECTRUM_USE_RESP Parameters . . . . . . . . . . . . . 51
6.7. verifyDevice Method . . . . . . . . . . . . . . . . . . . 51 6.7. verifyDevice Method . . . . . . . . . . . . . . . . . . . 52
6.7.1. DEV_VALID_REQ Parameters . . . . . . . . . . . . . . . 51 6.7.1. DEV_VALID_REQ Parameters . . . . . . . . . . . . . . . 52
6.7.2. DEV_VALID_RESP Parameters . . . . . . . . . . . . . . 52 6.7.2. DEV_VALID_RESP Parameters . . . . . . . . . . . . . . 53
6.8. Sub-message Schemas . . . . . . . . . . . . . . . . . . . 53 6.8. Sub-message Schemas . . . . . . . . . . . . . . . . . . . 54
6.8.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . 53 6.8.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . 54
6.8.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . 55 6.8.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . 56
6.8.3. AntennaCharacteristics . . . . . . . . . . . . . . . . 56 6.8.3. AntennaCharacteristics . . . . . . . . . . . . . . . . 57
6.8.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . 57 6.8.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . 58
6.8.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . 57 6.8.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . 59
6.8.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . 59 6.8.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . 60
6.8.7. Spectrum . . . . . . . . . . . . . . . . . . . . . . . 59 6.8.7. Spectrum . . . . . . . . . . . . . . . . . . . . . . . 61
6.8.8. FrequencyRange . . . . . . . . . . . . . . . . . . . . 60 6.8.8. FrequencyRange . . . . . . . . . . . . . . . . . . . . 62
6.8.9. EventTime . . . . . . . . . . . . . . . . . . . . . . 61 6.8.9. EventTime . . . . . . . . . . . . . . . . . . . . . . 63
6.8.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . 62 6.8.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . 64
6.8.11. GeoSpectrumSchedule . . . . . . . . . . . . . . . . . 63 6.8.11. GeoSpectrumSchedule . . . . . . . . . . . . . . . . . 65
6.8.12. DeviceValidity . . . . . . . . . . . . . . . . . . . . 63 6.8.12. DeviceValidity . . . . . . . . . . . . . . . . . . . . 65
6.8.13. Additional Properties . . . . . . . . . . . . . . . . 64 6.8.13. Additional Properties . . . . . . . . . . . . . . . . 66
7. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . . . 64 7. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . . . 66
8. Example Messages . . . . . . . . . . . . . . . . . . . . . . . 65 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 67
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65 8.1. Defining New Message Parameters . . . . . . . . . . . . . 67
10. Security Considerations . . . . . . . . . . . . . . . . . . . 65 8.2. Defining Ruleset Identifiers . . . . . . . . . . . . . . . 68
10.1. Assurance of Proper Database . . . . . . . . . . . . . . . 66 8.3. Defining Additional Error Codes . . . . . . . . . . . . . 68
10.2. Protection Against Modification . . . . . . . . . . . . . 67
10.3. Protection Against Eavesdropping . . . . . . . . . . . . . 67 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68
10.4. Client Authentication Considerations . . . . . . . . . . . 67 9.1. PAWS Parameters Registry . . . . . . . . . . . . . . . . . 69
11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 68 9.1.1. Registration Template . . . . . . . . . . . . . . . . 69
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 68 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 69
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 68 9.2. PAWS Ruleset ID Registry . . . . . . . . . . . . . . . . . 70
13.1. Normative References . . . . . . . . . . . . . . . . . . . 68 9.2.1. Registration Template . . . . . . . . . . . . . . . . 70
13.2. Informative References . . . . . . . . . . . . . . . . . . 69 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 71
Appendix A. Changes / Author Notes. . . . . . . . . . . . . . . . 70 9.3. PAWS Error Code Registry . . . . . . . . . . . . . . . . . 71
Appendix B. Regulatory-specific Notes . . . . . . . . . . . . . . 70 9.3.1. Registration Template . . . . . . . . . . . . . . . . 72
B.1. US / FCC . . . . . . . . . . . . . . . . . . . . . . . . . 70 9.3.2. Initial Registry Contents . . . . . . . . . . . . . . 72
B.2. UK / Ofcom . . . . . . . . . . . . . . . . . . . . . . . . 71 10. Security Considerations . . . . . . . . . . . . . . . . . . . 72
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 71 10.1. Assurance of Proper Database . . . . . . . . . . . . . . . 73
10.2. Protection Against Modification . . . . . . . . . . . . . 73
10.3. Protection Against Eavesdropping . . . . . . . . . . . . . 74
10.4. Client Authentication Considerations . . . . . . . . . . . 74
11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 74
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 75
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 75
13.1. Normative References . . . . . . . . . . . . . . . . . . . 75
13.2. Informative References . . . . . . . . . . . . . . . . . . 76
Appendix A. Changes / Author Notes. . . . . . . . . . . . . . . . 77
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 77
1. Introduction 1. Introduction
This section provides some high level introductory material. Readers This section provides some high level introductory material. Readers
are strongly encouraged to read Protocol to Access White Space are strongly encouraged to read Protocol to Access White Space
database: PS, use cases and rqmts database: PS, use cases and rqmts
[I-D.ietf-paws-problem-stmt-usecases-rqmts] for use cases, [I-D.ietf-paws-problem-stmt-usecases-rqmts] for use cases,
requirements, and additional background. requirements, and additional background.
A geospatial database can track available spectrum (in accordance A geospatial database can track available spectrum (in accordance
skipping to change at page 7, line 9 skipping to change at page 7, line 9
8. The Database responds with an available-spectrum response 8. The Database responds with an available-spectrum response
message in the body of the HTTP response. message in the body of the HTTP response.
9. Depending on regulatory domain requirements and database 9. Depending on regulatory domain requirements and database
implementation, the Master Device sends a spectrum-usage implementation, the Master Device sends a spectrum-usage
notification message to the Database. notification message to the Database.
10. If the Database receives a spectrum-usage notification message, 10. If the Database receives a spectrum-usage notification message,
it responds by sending the Master Device a spectrum-usage it responds by sending the Master Device a spectrum-usage
acknowledgement message. acknowledgement message.
3.1. Multi-ruleset Support
For a Master Device that supports multiple rule sets and operates
with multiple databases in multiple regulatory domains, the PAWS
protocol supports the following sequence of operations for each
request by the Master Device:
1. The Master Device includes in its request the identifier of one
or more of the rule sets it supports
2. The Database may use the rule-set list to determine its response,
for example, to select the list of required parameters
3. If required parameters are missing from the request, the Database
responds with a REQUIRED error and a list of the missing
parameters
4. The Master Device makes the request again, adding the missing
parameters
5. The Database responds to the request, including the identifier of
the applicable rule set
6. The Master Device uses the indicated rule set to determine how to
interpret the Database response
NOTE: Regulatory rules contain many device-only requirements that
govern device behavior, independent of any database rules. These
requirements may be complex and involve device behavior that are not
easily parameterized. The ruleset-id parameter provides a mechanism
for the Database to inform the Master Device of the applicable rule
set without having to express device-side behavior within the
protocol. The rule-set identifier could be a string that contains
the entity that established the rules and version information, such
as "FccTvBandWhiteSpace-2010".
By separating the regulatory "authority" from the "ruleset-id", it
allows the protocol to support multiple regulatory authorities that
use the same device-side rule set. It also allows support for a
single authority to define multiple rule sets.
4. Protocol Functionalities 4. Protocol Functionalities
The PAWS protocol consists of several components: The PAWS protocol consists of several components:
o Database Discovery (Section 4.1) MUST be supported by the Master o Database Discovery (Section 4.1) MUST be supported by the Master
Device Device
o Initialization (Section 4.2) MAY be used by the Master Device and o Initialization (Section 4.2) MAY be used by the Master Device and
MUST be implemented by the Database. MUST be implemented by the Database.
o Device Registration (Section 4.3) MAY be used by the Master Device o Device Registration (Section 4.3) MAY be used by the Master Device
and MAY be implemented by the Database. and MAY be implemented by the Database.
o Available Spectrum Query (Section 4.4) MUST be supported by Master o Available Spectrum Query (Section 4.4) MUST be supported by Master
Device and the Database. Device and the Database.
o Device Validation (Section 4.5) MAY be used by the Master Device o Device Validation (Section 4.5) MAY be used by the Master Device
and MUST be implemented by the Database if the regulatory domain and MUST be implemented by the Database if the regulatory domain
requires device validation. requires device validation.
skipping to change at page 9, line 13 skipping to change at page 10, line 8
parameters it does not understand. parameters it does not understand.
4.2.2. INIT_RESP 4.2.2. INIT_RESP
The initialization response message communicates database parameters The initialization response message communicates database parameters
to the requesting device. to the requesting device.
+-------------------------------------+ +-------------------------------------+
|INIT_RESP | |INIT_RESP |
+--------------------------+----------+ +--------------------------+----------+
|rulesetInfo:RulesetInfo | required| |rulesetInfo:RulesetInfo | required |
|.....................................| |.....................................|
|*other:any | depends | |*other:any | depends |
+--------------------------+----------+ +--------------------------+----------+
Parameters: Parameters:
rulesetInfo: This RulesetInfo (Section 5.6) parameter MUST be rulesetInfo: This RulesetInfo (Section 5.6) parameter MUST be
included in the response. This parameter specifies the regulatory included in the response. This parameter specifies the regulatory
domain and parameters applicable for that domain. The Database domain and parameters applicable for that domain. The Database
MUST include the "authority" that defines the regulatory domain MUST include the "authority" that defines the regulatory domain
skipping to change at page 10, line 47 skipping to change at page 11, line 47
deviceOwner: The DeviceOwner (Section 5.5) information is REQUIRED. deviceOwner: The DeviceOwner (Section 5.5) information is REQUIRED.
other: Regulatory domains MAY require additional registration other: Regulatory domains MAY require additional registration
parameters. To simplify its registration logic, the Device MAY parameters. To simplify its registration logic, the Device MAY
send a union of the registration information required by all send a union of the registration information required by all
supported regulatory domains. The Database MUST ignore all supported regulatory domains. The Database MUST ignore all
parameters it does not understand . parameters it does not understand .
4.3.2. REGISTRATION_RESP 4.3.2. REGISTRATION_RESP
The registration response message simply acknowledges receipt of the The registration response message simply acknowledges receipt of the
request and is otherwise empty. request and is otherwise empty. Future extensions may add parameters
to this message.
+-------------------------------------+ +-------------------------------------+
|REGISTRATION_RESP | |REGISTRATION_RESP |
+--------------------------+----------+ +--------------------------+----------+
|*other:any | depends |
+--------------------------+----------+ +--------------------------+----------+
4.4. Available Spectrum Query 4.4. Available Spectrum Query
To obtain the available spectrum from the Database, a Master Device To obtain the available spectrum from the Database, a Master Device
sends a request that contains its geo-location and any parameters sends a request that contains its geo-location and any parameters
required by the regulatory rules (such as device identifier, required by the regulatory rules (such as device identifier,
capabilities, and characteristics). The Database returns a response capabilities, and characteristics). The Database returns a response
that describes what frequencies are available, at what permissible that describes what frequencies are available, at what permissible
operating power levels, and a schedule of when they are available. operating power levels, and a schedule of when they are available.
skipping to change at page 14, line 29 skipping to change at page 16, line 11
The response message for the Available Spectrum Query contains a The response message for the Available Spectrum Query contains a
schedule of available spectrum for the Device. schedule of available spectrum for the Device.
+---------------------------------------+ +---------------------------------------+
|AVAIL_SPECTRUM_RESP | |AVAIL_SPECTRUM_RESP |
+----------------------------+----------+ +----------------------------+----------+
|deviceDesc:DeviceDescriptor | required | |deviceDesc:DeviceDescriptor | required |
|spectrumSchedules:list | required |-------+ |spectrumSchedules:list | required |-------+
|needsSpectrumReport:bool | optional | | |needsSpectrumReport:bool | optional | |
|rulesetId:string | optional | |
|............................|..........| | |............................|..........| |
|location:GeoLocation | optional | | |location:GeoLocation | optional | |
+----------------------------+----------+ | 0..* +----------------------------+----------+ | 0..*
V V
+-----------------------------+ +-----------------------------+
|SpectrumSchedule | |SpectrumSchedule |
+------------------+----------+ +------------------+----------+
|time:EventTime | required | |time:EventTime | required |
|spectrum:Spectrum | required | |spectrum:Spectrum | required |
+------------------+----------+ +------------------+----------+
skipping to change at page 15, line 4 skipping to change at page 16, line 33
Parameters: Parameters:
deviceDesc: The Database MUST include the DeviceDescriptor deviceDesc: The Database MUST include the DeviceDescriptor
(Section 5.2) specified in the AVAIL_SPECTRUM_REQ message (Section 5.2) specified in the AVAIL_SPECTRUM_REQ message
spectrumSchedules: The SpectrumSchedule (Section 5.10) list is spectrumSchedules: The SpectrumSchedule (Section 5.10) list is
REQUIRED (though it MAY be empty if no spectrum is available). REQUIRED (though it MAY be empty if no spectrum is available).
The Database MAY return more than one SpectrumSchedule The Database MAY return more than one SpectrumSchedule
(Section 6.8.10) to represent future changes to the available (Section 6.8.10) to represent future changes to the available
spectrum. How far in advance a schedule may be provided depends spectrum. How far in advance a schedule may be provided depends
on the regulatory domain. on the regulatory domain.
needsSpectrumReport: For regulatory domains that require a spectrum- needsSpectrumReport: For regulatory domains that require a spectrum-
usage report from devices, the Database MUST return true for this usage report from devices, the Database MUST return true for this
parameter. The default value is false. parameter. The default value is false.
rulesetId: The Database SHOULD return the identifier of the
applicable rule set for the response (see Ruleset ID Registry
(Section 9.2)). If included, the Device MUST use the
corresponding rule set to interpret the response.
location: The Database MAY copy other elements from the request, location: The Database MAY copy other elements from the request,
such as the GeoLocation (Section 5.1) of the Device. The Device such as the GeoLocation (Section 5.1) of the Device. The Device
MUST ignore any parameters it does not understand. MUST ignore any parameters it does not understand.
4.4.2.1. Update Requirements 4.4.2.1. Update Requirements
When the stop time specified in the schedule has been reached, the When the stop time specified in the schedule has been reached, the
Device: Device:
o MUST obtain a new spectrum-availability schedule, either by using o MUST obtain a new spectrum-availability schedule, either by using
the next one in the list (if provided) or making another Available the next one in the list (if provided) or making another Available
skipping to change at page 17, line 11 skipping to change at page 18, line 41
The response message for the batch Available Spectrum Query contains The response message for the batch Available Spectrum Query contains
a schedule of available spectrum for the Device at multiple a schedule of available spectrum for the Device at multiple
locations. locations.
+---------------------------------------+ +---------------------------------------+
|AVAIL_SPECTRUM_BATCH_RESP | |AVAIL_SPECTRUM_BATCH_RESP |
+----------------------------+----------+ +----------------------------+----------+
|deviceDesc:DeviceDescriptor | required | |deviceDesc:DeviceDescriptor | required |
|geoSpectrumSchedules:list | required |-------+ |geoSpectrumSchedules:list | required |-------+
|needsSpectrumReport:bool | optional | | |needsSpectrumReport:bool | optional | |
|rulesetId:string | optional | |
+----------------------------+----------+ | 0..* +----------------------------+----------+ | 0..*
V V
+---------------------------------+ +---------------------------------+
|GeoSpectrumSchedule | |GeoSpectrumSchedule |
+----------------------+----------+ +----------------------+----------+
|location:GeoLocation | required | |location:GeoLocation | required |
|spectrumSchedule:list | required | |spectrumSchedule:list | required |
+----------------------+----------+ +----------------------+----------+
Parameters: Parameters:
skipping to change at page 17, line 38 skipping to change at page 19, line 21
to the available spectrum. How far in advance a schedule may be to the available spectrum. How far in advance a schedule may be
provided depends on the regulatory domain. The Database MAY provided depends on the regulatory domain. The Database MAY
return available spectrum for fewer locations than requested. The return available spectrum for fewer locations than requested. The
Device MUST NOT make any assumptions on the order of the entries Device MUST NOT make any assumptions on the order of the entries
in the list and MUST use the location value in each in the list and MUST use the location value in each
GeoSpectrumSchedule entry to match available spectrum to a GeoSpectrumSchedule entry to match available spectrum to a
location. location.
needsSpectrumReport: For regulatory domains that require a spectrum- needsSpectrumReport: For regulatory domains that require a spectrum-
usage report from devices, the Database MUST return true for this usage report from devices, the Database MUST return true for this
parameter. The default value is false. parameter. The default value is false.
rulesetId: The Database SHOULD return the identifier of the
applicable rule set for the response (see Ruleset ID Registry
(Section 9.2)). If included, the Device MUST use the
corresponding rule set to interpret the response.
See Update Requirements (Section 4.4.2.1) for when the Device must See Update Requirements (Section 4.4.2.1) for when the Device must
update its available spectrum data. update its available spectrum data.
4.4.5. SPECTRUM_USE_NOTIFY 4.4.5. SPECTRUM_USE_NOTIFY
The spectrum-use notification message MUST contain the geo-location The spectrum-use notification message MUST contain the geo-location
of the Device and parameters required by the regulatory domain. of the Device and parameters required by the regulatory domain.
+---------------------------------------+ +---------------------------------------+
skipping to change at page 23, line 9 skipping to change at page 24, line 36
The device descriptor contains parameters that identify the specific The device descriptor contains parameters that identify the specific
device, such as its manufacturer serial number, regulatory-specific device, such as its manufacturer serial number, regulatory-specific
ID (e.g., FCC ID), and any other device characteristics required by ID (e.g., FCC ID), and any other device characteristics required by
regulatory domains. regulatory domains.
+----------------------------------------------------+ +----------------------------------------------------+
|DeviceDescriptor | |DeviceDescriptor |
+--------------------+-------------------------------+ +--------------------+-------------------------------+
|serialNumber:string | required | |serialNumber:string | required |
|rulesetIds:list | optional |
|fccId:string | depends on regulatory domain | |fccId:string | depends on regulatory domain |
|....................|...............................| |....................|...............................|
|*deviceType:string | depends on regulatory domain | |*deviceType:string | depends on regulatory domain |
|*RAT:string | depends on regulatory domain | |*RAT:string | depends on regulatory domain |
|*other:any | | |*other:any | |
+--------------------+-------------------------------+ +--------------------+-------------------------------+
Parameters: Parameters:
serialNumber: The manufacturer's device serial number is REQUIRED. serialNumber: The manufacturer's device serial number is REQUIRED.
rulesetIds: List of identifiers for rule sets supported by the
device (see Ruleset ID Registry (Section 9.2)). A Database MAY
require that the device provides this list before servicing the
device requests. If the Database does not support any of the rule
sets specified in the list, the Database MAY refuse to service the
device requests. See Section 5.6 for discussion on rule-set
identifier.
fccId: The Device's FCC ID may be required for some regulatory fccId: The Device's FCC ID may be required for some regulatory
domains. domains.
Additional parameters in the DeviceDescriptor depend on each Additional parameters in the DeviceDescriptor depend on each
regulatory domain, including certification IDs for other regulatory regulatory domain and are listed in the figure for illustrative
domains. purposes. It can be extended, for example, to include certification
IDs for additional regulatory domains.
[Editor's Note: The descriptor probably should include an optional a
list of rule-set identifiers supported by the Device. This would
enable a database to determine the appropriate response. Also
consider using IANA to define the names of the rule sets and
parameters within the Device Descriptor.]
5.3. AntennaCharacteristics 5.3. AntennaCharacteristics
Antenna characteristics provide additional information, such as the Antenna characteristics provide additional information, such as the
antenna height, antenna type, etc. Whether antenna characteristics antenna height, antenna type, etc. Whether antenna characteristics
must be provided in a request depends on the device type and must be provided in a request depends on the device type and
regulatory domain. regulatory domain.
+--------------------------------------------------------+ +--------------------------------------------------------+
|AntennaCharacteristics | |AntennaCharacteristics |
skipping to change at page 25, line 44 skipping to change at page 27, line 32
This contains parameters for the rule set of a regulatory domain that This contains parameters for the rule set of a regulatory domain that
is communicated using the Initialization component (Section 4.2). is communicated using the Initialization component (Section 4.2).
+-----------------------------------+ +-----------------------------------+
|RulesetInfo | |RulesetInfo |
+-----------------------------------+ +-----------------------------------+
|authority:string | required | |authority:string | required |
|maxLocationChange:float | required | |maxLocationChange:float | required |
|maxPollingSecs:int | required | |maxPollingSecs:int | required |
|maxValiditySecs:int | required | |rulesetIds: list | optional |
|...................................| |...................................|
|*other:any | depends | |*other:any | depends |
+------------------------+----------+ +------------------------+----------+
Parameters: Parameters:
authority: A string that indicates the regulatory domain to which authority: A string that indicates the regulatory domain to which
the ruleset applies is REQUIRED. It MUST use the 2-letter country the rule set applies is REQUIRED. It MUST use the 2-letter
codes defined by Country Codes - ISO 3166 [ISO3166-1]. country codes defined by Country Codes - ISO 3166 [ISO3166-1].
maxLocationChange: The maximum location change in meters is maxLocationChange: The maximum location change in meters is
REQUIRED. When the Device changes location by more than this REQUIRED. When the Device changes location by more than this
specified distance, it MUST contact the Database to get the specified distance, it MUST contact the Database to get the
available spectrum for the new location. If the Device is using available spectrum for the new location. If the Device is using
spectrum that is no longer available, it MUST stop operation in spectrum that is no longer available, it MUST stop operation in
those frequencies immediately. those frequencies immediately.
maxPollingSecs: The maximum duration, in seconds, between requests maxPollingSecs: The maximum duration, in seconds, between requests
for available spectrum is REQUIRED. The Device MUST contact the for available spectrum is REQUIRED. The Device MUST contact the
Database to get available spectrum no less frequently than this Database to get available spectrum no less frequently than this
duration. If the new spectrum information indicates that the duration. If the new spectrum information indicates that the
Device is using spectrum that is no longer available, it MUST stop Device is using spectrum that is no longer available, it MUST stop
operation in those frequencies immediately. operation in those frequencies immediately.
maxValiditySecs: The maximum duration that the available-spectrum
information may be considered valid is REQUIRED. When the Device rulesetIds: The Database SHOULD return the identifier of the
is unable to contact the Database, it MAY continue to use the applicable rule set (see Ruleset ID Registry (Section 9.2)). If
latest available-spectrum information at its location until its included, the Device MUST use the corresponding rule set to
validity expires. The expiration is determined by adding interpret the response.
maxValiditySecs to the timestamp of the AVAIL_SPECTRUM_RESP that
provided the latest available-spectrum information.
other: This message is intended to be extensible with other other: This message is intended to be extensible with other
regulatory-specific parameters. Devices MUST ignore all regulatory-specific parameters. Devices MUST ignore all
parameters in the message it does not understand. parameters in the message it does not understand.
[Editor's Note: Rule-set information contain parameters from the
Database that control behavior of the Device. Rules that govern
device behavior may be hard to characterize, in a declarative
fashion, with just a set of parameters that is easy to understand,
especially when there may be coupling between parameters.
Would it be simpler to characterize rule sets by a concise list of
identifiers, such as "FCC-WhiteSpace-2010", "Ofcom-WhiteSpace-2013"?
An advantage of named rule sets is that it allows new regulatory
domain to easily adopt existing rulesets and allow existing Devices
to work "automatically" within a new regulatory domain with just a
few configured rule sets.]
5.7. Spectrum 5.7. Spectrum
Available spectrum can logically be characterized by a list of Available spectrum can logically be characterized by a list of
frequency ranges and permissible power levels for each range. frequency ranges and permissible power levels for each range.
+-------------------------------+ +-------------------------------+
|Spectrum | |Spectrum |
+---------------------+---------+ +---------------------+---------+
|bandwidth:float |required | +---------------------------+ |bandwidth:float |required | +---------------------------+
|frequencyRanges:list |required |------>|FrequencyRange | |frequencyRanges:list |required |------>|FrequencyRange |
skipping to change at page 30, line 31 skipping to change at page 31, line 43
Parameters: Parameters:
code An integer code that indicates the error type. code An integer code that indicates the error type.
message A short description of the error. It MAY be in any message A short description of the error. It MAY be in any
language. language.
data The Database MAY include additional data. For some errors, data The Database MAY include additional data. For some errors,
additional data may be required. The Device MUST ignore any data additional data may be required. The Device MUST ignore any data
parameters it does not understand. parameters it does not understand.
The following table defines valid error codes. They are lossely The following table defines valid error codes. They are loosely
grouped into the following categories: grouped into the following categories:
-100s Indicates compatibility issues, e.g., version mismatch, -100s Indicates compatibility issues, e.g., version mismatch,
unsupported or unimplemented features. unsupported or unimplemented features.
-200s Indicates that the Device request contains an error that needs -200s Indicates that the Device request contains an error that needs
to be modified before making another request. to be modified before making another request.
-300s Indicates authorization-related issues. -300s Indicates authorization-related issues.
Code Name Description Code Name Description
---- ---------------- ----------------------------------------------- ---- ---------------- -----------------------------------------------
-100 (reserved)
-101 VERSION The Database does not support the specified -101 VERSION The Database does not support the specified
version of the message. version of the message.
-102 UNSUPPORTED The Database does not support the Device. For -102 UNSUPPORTED The Database does not support the Device. For
example, it does not support the regulatory example, it does not support the regulatory
domain specified in the request. domain specified in the request.
-103 UNIMPLEMENTED The Database does not implement the optional -103 UNIMPLEMENTED The Database does not implement the optional
request or optional feature. request or optional feature.
-104 OUTSIDE_COVERAGE The specified geo-location is outside the -104 OUTSIDE_COVERAGE The specified geo-location is outside the
coverage area of the Database. coverage area of the Database.
-200 (reserved)
-201 REQUIRED A required parameter is missing. The Database -201 REQUIRED A required parameter is missing. The Database
MUST include a list of the required parameter MUST include a list of the required parameter
names. The Database MAY include only names of names. The Database MAY include only names of
parameters that are missing, but MAY include a parameters that are missing, but MAY include a
full list. When providing only a listing of full list. When providing only a listing of
missing parameters, the Database SHOULD include missing parameters, the Database SHOULD include
the full list to minimize number of re-queries the full list of missing parameters to minimize
from the Device. number of re-queries from the Device.
-202 INVALID_VALUE A parameter value is invalid in some way. The -202 INVALID_VALUE A parameter value is invalid in some way. The
Database SHOULD include a message indicating Database SHOULD include a message indicating
which parameter(s) and why the value is which parameter(s) and why the value is
invalid. invalid.
-300 (reserved)
-301 UNAUTHORIZED The Device is not authorized to used the -301 UNAUTHORIZED The Device is not authorized to used the
Database. Authorization may be determined by Database. Authorization may be determined by
regulatory rules or be dependent on prior regulatory rules or be dependent on prior
arrangement between the Device and Database. arrangement between the Device and Database.
-302 NOT_REGISTERED Device registration required, but the Device is -302 NOT_REGISTERED Device registration required, but the Device is
not registered. not registered.
Table 1: Error Codes Table 1: Error Codes
5.13.1. REQUIRED Error 5.13.1. REQUIRED Error
skipping to change at page 31, line 43 skipping to change at page 33, line 18
|code:int | required | |code:int | required |
|message:string | optional | +---------------------------+ |message:string | optional | +---------------------------+
|data:Parameters | optional |--->|Parameters | |data:Parameters | optional |--->|Parameters |
+----------------+----------+ +----------------+----------+ +----------------+----------+ +----------------+----------+
|parameters:list | required | |parameters:list | required |
|...........................| |...........................|
|*other:any | optional | |*other:any | optional |
+----------------+----------+ +----------------+----------+
Parameters: Parameters:
parameters List of parameter names. parameters List of parameter names. The name of a parameter SHOULD
be expressed using dotted notation, when appropriate, e.g.,
"deviceDesc.serialNumber".
other The Database MAY include other parameters. The Device MUST other The Database MAY include other parameters. The Device MUST
ignore all parameters it does not understand. ignore all parameters it does not understand.
6. Message Encoding 6. Message Encoding
The PAWS protocol is encoded using JSON-RPC [JSON-RPC] (see also The PAWS protocol is encoded using JSON-RPC [JSON-RPC] (see also
JavaScript Object Notation (JSON) [RFC4627]). Each component JavaScript Object Notation (JSON) [RFC4627]). Each component
described in Protocol Functionalities (Section 4) corresponds to one described in Protocol Functionalities (Section 4) corresponds to one
or more JSON-RPC methods. This section provides the JSON schema for or more JSON-RPC methods. This section provides the JSON schema for
each of the protocol messages and parameters defined in sections each of the protocol messages and parameters defined in sections
skipping to change at page 33, line 26 skipping to change at page 34, line 48
Depending on prior arrangement between a Database and Device, the Depending on prior arrangement between a Database and Device, the
Request and Response MAY contain additional parameters. The Database Request and Response MAY contain additional parameters. The Database
or Device MUST ignore all parameters it does not understand. or Device MUST ignore all parameters it does not understand.
6.2. init Method 6.2. init Method
This section describes the encoding for the JSON-RPC "init" method This section describes the encoding for the JSON-RPC "init" method
that represents the Initialization functionality (Section 4.2). that represents the Initialization functionality (Section 4.2).
6.2.1. INIT_REQ Schema 6.2.1. INIT_REQ Parameters
The JSON encoding of the Initialization request message INIT_REQ The JSON encoding of the Initialization request message INIT_REQ
(Section 4.2.1) is described by the following schema: (Section 4.2.1) is described by the following schema:
{ {
"name": "INIT_REQ", "name": "INIT_REQ",
"type": "object", "type": "object",
"properties": { "properties": {
"type": "INIT_REQ", "type": "INIT_REQ",
"version": { "version": {
skipping to change at page 41, line 42 skipping to change at page 42, line 42
"items": "SpectrumSchedule", "items": "SpectrumSchedule",
"required": true "required": true
}, },
"needsSpectrumReport": { "needsSpectrumReport": {
"type": "boolean", "type": "boolean",
"description": "For regulatory domains that require a " + "description": "For regulatory domains that require a " +
"spectrum-usage report from devices, the Database MUST " + "spectrum-usage report from devices, the Database MUST " +
"return true for this parameter.", "return true for this parameter.",
"default": false, "default": false,
"required": false "required": false
},
"rulesetId": {
"type": "string",
"description": "The identifier of the applicable rule set.",
"required": false
} }
} }
} }
Example "getSpectrum" JSON-RPC response: Example "getSpectrum" JSON-RPC response:
{ {
"result": { "result": {
"type": "AVAILABLE_SPECTRUM_RESP", "type": "AVAILABLE_SPECTRUM_RESP",
"version": "1.0", "version": "1.0",
skipping to change at page 44, line 12 skipping to change at page 45, line 12
AVAIL_SPECTRUM_BATCH_REQ (Section 4.4.3) is described by the AVAIL_SPECTRUM_BATCH_REQ (Section 4.4.3) is described by the
following schema. This an OPTIONAL feature of the Database. following schema. This an OPTIONAL feature of the Database.
{ {
"name": "AVAIL_SPECTRUM_BATCH_REQ", "name": "AVAIL_SPECTRUM_BATCH_REQ",
"type": "object", "type": "object",
"properties": { "properties": {
"type": "AVAILABLE_SPECTRUM_BATCH_REQ", "type": "AVAILABLE_SPECTRUM_BATCH_REQ",
"version": { "version": {
"type": "string", "type": "string",
"required": true "required": true
}, },
"deviceDesc": { "deviceDesc": {
"type": "DeviceDescriptor", "type": "DeviceDescriptor",
"required": true "required": true
}, },
"locations": { "locations": {
"type": "array", "type": "array",
"description": "At least one device location is required. " + "description": "At least one device location is required. " +
"Additional (anticipated) locations can also be included, " + "Additional (anticipated) locations can also be included, " +
"as permitted by regulatory domain,", "as permitted by regulatory domain,",
skipping to change at page 46, line 12 skipping to change at page 47, line 12
AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) is described by the AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) is described by the
following schema: following schema:
{ {
"name": "AVAIL_SPECTRUM_BATCH_RESP", "name": "AVAIL_SPECTRUM_BATCH_RESP",
"type": "object", "type": "object",
"properties": { "properties": {
"type": "AVAILABLE_SPECTRUM_BATCH_RESP", "type": "AVAILABLE_SPECTRUM_BATCH_RESP",
"version": { "version": {
"type": "string", "type": "string",
"required": true "required": true
}, },
"timestamp": { "timestamp": {
"type": "string", "type": "string",
"description": "Timestamp of the response of the form " + "description": "Timestamp of the response of the form " +
"YYYY-MM-DDThh:mm:ssZ. This SHOULD be used by the Device " + "YYYY-MM-DDThh:mm:ssZ. This SHOULD be used by the Device " +
"as a reference for the start and stop times in the " + "as a reference for the start and stop times in the " +
"spectrum schedule", "spectrum schedule",
"required": true "required": true
}, },
"deviceDesc": { "deviceDesc": {
"type": "DeviceDescriptor", "type": "DeviceDescriptor",
"required": true "required": true
}, },
"geoSpectrumSchedules": { "geoSpectrumSchedules": {
"type": "array", "type": "array",
"description": "For each location, the Database MAY return " + "description": "For each location, the Database MAY return " +
"more than one schedule to represent future changes " + "more than one schedule to represent future changes " +
"to the available spectrum. This array MAY be empty if " + "to the available spectrum. This array MAY be empty if " +
"there is no available spectrum.", "there is no available spectrum.",
"items": "GeoSpectrumSchedule", "items": "GeoSpectrumSchedule",
"required": true "required": true
}, },
"needsSpectrumReport": { "needsSpectrumReport": {
"type": "boolean", "type": "boolean",
"description": "For regulatory domains that require a " + "description": "For regulatory domains that require a " +
"spectrum-usage report from devices, the Database MUST " + "spectrum-usage report from devices, the Database MUST " +
"return true for this parameter.", "return true for this parameter.",
"default": false, "default": false,
"required": false "required": false
},
"rulesetId": {
"type": "string",
"description": "The identifier of the applicable rule set.",
"required": false
} }
} }
} }
Example "getSpectrumBatch" JSON-RPC response: Example "getSpectrumBatch" JSON-RPC response:
{ {
"result": { "result": {
"type": "AVAILABLE_SPECTRUM_BATCH_RESP", "type": "AVAILABLE_SPECTRUM_BATCH_RESP",
"version": "1.0", "version": "1.0",
skipping to change at page 49, line 15 skipping to change at page 50, line 15
{ {
"name": "SPECTRUM_USE_NOTIFY", "name": "SPECTRUM_USE_NOTIFY",
"type": "object", "type": "object",
"properties": { "properties": {
"type": "SPECTRUM_USE_NOTIFY", "type": "SPECTRUM_USE_NOTIFY",
"version": { "version": {
"type": "string", "type": "string",
"required": true "required": true
}, },
"deviceDesc": { "deviceDesc": {
"type": "DeviceDescriptor", "type": "DeviceDescriptor",
"required": true "required": true
}, },
"location": { "location": {
"type": "GeoLocation", "type": "GeoLocation",
"required": true "required": true
}, },
"spectra": { "spectra": {
"type": "array", "type": "array",
"description": "The spectrum anticipated to be used by " + "description": "The spectrum anticipated to be used by " +
"the Device.", "the Device.",
skipping to change at page 53, line 44 skipping to change at page 54, line 44
This section defines the schema for Protocol Parameters (Section 5) This section defines the schema for Protocol Parameters (Section 5)
embedded in PAWS request and response messages. embedded in PAWS request and response messages.
6.8.1. GeoLocation 6.8.1. GeoLocation
This parameter is used to specify the GeoLocation (Section 5.1) of This parameter is used to specify the GeoLocation (Section 5.1) of
the Device. The geometric shapes represent the JSON encoding shapes the Device. The geometric shapes represent the JSON encoding shapes
defined in GEOPRIV Presence Information Data Format Location Object defined in GEOPRIV Presence Information Data Format Location Object
[RFC5491]. [RFC5491].
{ {
"name": "GeoLocation", "name": "GeoLocation",
"type": "object", "type": "object",
"properties": { "properties": {
"point": { "point": {
"description": "A single location, with optional " + "description": "A single location, with optional " +
"uncertainty measures", "uncertainty measures",
"type": "Ellipse", "type": "Ellipse",
"required": false "required": false
}, },
skipping to change at page 56, line 5 skipping to change at page 57, line 5
} }
6.8.2. DeviceDescriptor 6.8.2. DeviceDescriptor
The DeviceDescriptor (Section 5.2) contains parameters that identify The DeviceDescriptor (Section 5.2) contains parameters that identify
the specific device, such as its manufacturer serial number, the specific device, such as its manufacturer serial number,
regulatory-specific ID (e.g., FCC ID), and any other device regulatory-specific ID (e.g., FCC ID), and any other device
characteristics required by regulatory domains, such as device-type characteristics required by regulatory domains, such as device-type
classification. classification.
{ {
"name": "DeviceDescriptor", "name": "DeviceDescriptor",
"type": "object", "type": "object",
"properties": { "properties": {
"serialNumber": { "serialNumber": {
"type": "string", "type": "string",
"required": true "required": true
}, },
"fccId": { "rulesetIds": {
"type": "string", "type": "array",
"description":"The device's FCC ID.", "description": "List of identifiers for rule sets supported " +
"required": false "by the device",
} "items": "string",
"required": false
},
"fccId": {
"type": "string",
"description":"The device's FCC ID.",
"required": false
} }
} }
}
6.8.3. AntennaCharacteristics 6.8.3. AntennaCharacteristics
AntennaCharacteristics (Section 5.3) provide additional information, AntennaCharacteristics (Section 5.3) provide additional information,
such as the antenna height, antenna type, etc. such as the antenna height, antenna type, etc.
{ {
"name": "AntennaCharacteristics", "name": "AntennaCharacteristics",
"type": "object", "type": "object",
"properties": { "properties": {
skipping to change at page 59, line 11 skipping to change at page 61, line 5
} }
} }
} }
6.8.6. RulesetInfo 6.8.6. RulesetInfo
RulesetInfo (Section 5.6) contains parameters for the rule set of a RulesetInfo (Section 5.6) contains parameters for the rule set of a
regulatory domain that is communicated using the Initialization regulatory domain that is communicated using the Initialization
component (Section 4.2). component (Section 4.2).
{ {
"name": "RulesetInfo", "name": "RulesetInfo",
"type": "object", "type": "object",
"description": "The rule set of a regulatory domain that is " + "description": "The rule set of a regulatory domain that is " +
"communicated to Devices in the Initialization Response " + "communicated to Devices in the Initialization Response " +
"message.", "message.",
"properties": { "properties": {
"authority": { "authority": {
"type": "string", "type": "string",
"description": "The regulatory domain at the specified " + "description": "The regulatory domain at the specified " +
"location. It is a 2-letter country codes defined by " + "location. It is a 2-letter country codes defined by " +
"ISO3166-1.", "ISO3166-1.",
"required": true "required": true
}, },
"maxLocationChange": { "maxLocationChange": {
"type": "number", "type": "number",
"description": "Maximum location change in meters.", "description": "Maximum location change in meters.",
"required": true "required": true
}, },
"maxPollingSecs": { "maxPollingSecs": {
"type": "integer", "type": "integer",
"description": "Maximum duration, in seconds, between " + "description": "Maximum duration, in seconds, between " +
"requests for available spectrum.", "requests for available spectrum.",
"required": true "required": true
}, },
"maxValiditySecs": { "rulesetId": {
"type": "string", "type": "string",
"description": "Maximum duration that the available-spectrum " + "description": "The identifier of the applicable rule set",
"information may be considered valid.", "required": false,
"required": true, }
} }
} }
}
6.8.7. Spectrum 6.8.7. Spectrum
Available Spectrum (Section 5.7) can logically be characterized by a Available Spectrum (Section 5.7) can logically be characterized by a
list of frequency ranges and permissible power levels for each range. list of frequency ranges and permissible power levels for each range.
{ {
"name": "Spectrum", "name": "Spectrum",
"type": "object", "type": "object",
"description": "A per-bandwidth list of frequency ranges with " + "description": "A per-bandwidth list of frequency ranges with " +
skipping to change at page 65, line 34 skipping to change at page 67, line 34
such as 404 (not found). such as 404 (not found).
The Database MAY redirect a PAWS request. The Master Device MUST The Database MAY redirect a PAWS request. The Master Device MUST
handle redirects by using the Location header provided by the server handle redirects by using the Location header provided by the server
in a 3xx response. When redirecting, the Master Device MUST observe in a 3xx response. When redirecting, the Master Device MUST observe
the delay indicated by the Retry-After header. The Master Device the delay indicated by the Retry-After header. The Master Device
MUST authenticate the Database that returns the redirect response MUST authenticate the Database that returns the redirect response
before following the redirect. The Master Device MUST authenticate before following the redirect. The Master Device MUST authenticate
the Database indicated in the redirect. the Database indicated in the redirect.
8. Example Messages 8. Extensibility
TBD 8.1. Defining New Message Parameters
New request or response parameters for use with the PAWS protocol are
defined and registered in the parameters registry following the
procedure in Section 9.1.
Parameter names MUST conform to the param-name ABNF and parameter
values syntax MUST be well-defined (e.g., using ABNF, or a reference
to the syntax of an existing parameter).
param-name = 1*name-char
name-char = ALPHA / DIGIT / "_"
The parameter name SHOULD be lowerCamelCase.
Unregistered vendor-specific parameter extensions that are not
commonly applicable, and are specific to the implementation details
of the Database where they are used SHOULD use a vendor-specific
prefix that is no likely to conflict with other registered values
(e.g., begin with 'companyname_').
8.2. Defining Ruleset Identifiers
A rule set represents a set of device-side requirements for which the
device has been certified. It typically corresponds to, but is not
limited to, a set of rules that govern a specific set of radio
spectrum for a regulatory domain.
Rule-set identifiers are defined and registered in the Ruleset ID
Registry following the procedure in Section 9.2. Ruleset ID values
MUST conform to the ruleset-id ABNF. If the Ruleset ID requires
additional parameters, they MUST be registered in the PAWS Parameters
Registry, as described by Section 9.1.
ruleset-id = 1*ruleset-char
ruleset-char = ALPHA / DIGIT / "_"
The form of a Ruleset ID value SHOULD be guided by the following:
o The value should describe the set of rules that allow a device to
operate within a regulatory domain. For example, it may include
the name of a regulatory body or a certification process
o The value should include version information, such as a year or
version number
8.3. Defining Additional Error Codes
Additional error codes MAY be defined to extend the set listed in
Section 5.13. Additional error codes MUST be registered, following
the procedures in Section 9.3. If the error code requires additional
response parameters, they MUST be registered in the PAWS Parameters
Registry, as described by Section 9.1.
By convention, the error code SHOULD be a negative integer value,
using one of the range of values defined in Error Codes
(Section 5.13). If an appropriate category does not exist, it MAY
use values in a different range.
9. IANA Considerations 9. IANA Considerations
9.1. PAWS Parameters Registry
TBD This specification establishes the PAWS Parameters Registry.
Additional parameters for inclusion in the PAWS protocol requests,
responses, or sub-messages are registered through the Specification
Required [RFC5226] process, after a two-week review period on the
[TBD]@ietf.org mailing list, on the advice of one or more Designated
Experts. To allow for the allocation of values prior to publication,
the Designated Expert(s) may approve registration once they are
satisfied that such a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request
for parameter: example"). [[ Editor's Note: The name of the mailing
list should be determined in consultation with the IESG and IANA.
Suggested name: paws-ext-review. ]]
Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.
IANA must only accept registry updates from the Designated Expert(s),
and should direct all requests for registration to the review mailing
list.
9.1.1. Registration Template
Parameter name: The name of the parameter (e.g., "example").
Parameter usage location: The location(s) where the parameter can be
used. The possible locations are the named requests, responses,
and messages defined in Protocol Functionalities (Section 4) and
Protocol Parameters (Section 5).
Specification document(s): Reference to the document that specifies
the parameter, preferably including a URI that can be used to
retrieve a copy of the document. An indication of the relevant
sections also may be included, but is not required.
9.1.2. Initial Registry Contents
The PAWS Parameters Registry enables protocol extensibility to
support any regulatory domain and rule set. The initial contents of
the registry, however, include only FCC-specific entries, because, as
of this writing, it is the only regulatory domain that has finalized
rules. There is no intent to restrict the protocol to FCC rules.
The PAWS Parameters Registry's initial contents are:
o Parameter name: fccId
o Parameter usage location: DeviceDescriptor (Section 5.2)
o Specification Document(s): [[ this document (Section 5.2) ]]
o Parameter name: fccTvbdDeviceType
o Parameter usage location: DeviceDescriptor (Section 5.2)
o Specification Document(s): [[ this document ]] Specifies the TV
Band White Space device type, as defined by the FCC. Valid values
are "FIXED", "MODE_1", "MODE_2".
9.2. PAWS Ruleset ID Registry
This specification establishes the PAWS Ruleset ID Registry.
Ruleset type names for inclusion in the PAWS protocol messages are
registered through the Specification Required [RFC5226] process,
after a two-week review period on the [TBD]@ietf.org mailing list, on
the advice of one or more Designated Experts. To allow for the
allocation of values prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a
specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request
for parameter: example"). [[ Editor's Note: The name of the mailing
list should be determined in consultation with the IESG and IANA.
Suggested name: paws-ext-review. ]]
Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.
IANA must only accept registry updates from the Designated Expert(s),
and should direct all requests for registration to the review mailing
list.
9.2.1. Registration Template
Ruleset name: The name of the rule set.
Additional message parameters: Additional parameters to associate
with the rulesetId parameter. New parameters MUST be registered
separately in the PAWS Parameters Registry, as described by
Section 8.1.
Specification Document(s): Reference to the document that specifies
the parameter, preferably including a URI that can be used to
retrieve a copy of the document. An indication of the relevant
sections also may be included, but is not required.
9.2.2. Initial Registry Contents
The PAWS Ruleset ID Registry enables protocol extensibility to
support any regulatory domain and rule set. The initial contents of
the registry, however, include only FCC-specific entries, because, as
of this writing, it is the only regulatory domain that has finalized
rules. There is no intent to restrict the protocol to FCC rules.
The initial content of the PAWS Ruleset ID Registry is:
o Ruleset name: FccTvBandWhiteSpace-2010
o Additional message parameters:
* fccId: Specifies a device's FCC certification ID. It is a
required parameter in DeviceDescriptor (Section 5.2).
* fccTvbdDeviceType: Specifies the type of TV-band White Space
device, as defined by the FCC rules. It is a required
parameter in DeviceDescriptor (Section 5.2).
o Specification Document(s): [[ this document ]] This rule set
refers to the FCC rules for TV-band White Space operations
established in the Code of Federal Regulations (CFR), Title 47,
Part 15, Subpart H (http://www.gpo.gov/fdsys/pkg/
CFR-2010-title47-vol1/pdf/
CFR-2010-title47-vol1-part15-subpartH.pdf).
9.3. PAWS Error Code Registry
This specification establishes the PAWS Error Code Registry.
Additional error codes for inclusion in the PAWS protocol error
message are registered through the Specification Required [RFC5226]
process, after a two-week review period on the [TBD]@ietf.org mailing
list, on the advice of one or more Designated Experts. To allow for
the allocation of values prior to publication, the Designated
Expert(s) may approve registration once they are satisfied that such
a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request
for parameter: example"). [[ Editor's Note: The name of the mailing
list should be determined in consultation with the IESG and IANA.
Suggested name: paws-ext-review. ]]
Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.
IANA must only accept registry updates from the Designated Expert(s),
and should direct all requests for registration to the review mailing
list.
9.3.1. Registration Template
Code: Integer value of the error code.
Name: Name of the error.
Additional parameters: Additional parameters that are returned in
the data portion of the error (See Section 5.13). New parameters
MUST be registered separately in the PAWS Parameters Registry, as
described by Section 9.1.
Description: Description of the error and its associated parameters,
if any.
9.3.2. Initial Registry Contents
Initial registry contents are defined in the Table of Error Codes
(Table 1).
10. Security Considerations 10. Security Considerations
PAWS is a protocol whereby a Master Device requests a schedule of PAWS is a protocol whereby a Master Device requests a schedule of
available spectrum at its location (or location of its Slave Devices) available spectrum at its location (or location of its Slave Devices)
before it (they) can operate using those frequencies. Whereas the before it (they) can operate using those frequencies. Whereas the
information provided by the Database must be accurate and conform to information provided by the Database must be accurate and conform to
applicable regulatory rules, the Database cannot enforce, through the applicable regulatory rules, the Database cannot enforce, through the
protocol, that a client device uses only the spectrum it provided. protocol, that a client device uses only the spectrum it provided.
In other words, devices can put energy in the air and cause In other words, devices can put energy in the air and cause
skipping to change at page 67, line 7 skipping to change at page 73, line 43
the Database authenticates its identity, either as a domain name or the Database authenticates its identity, either as a domain name or
IP address, to the Master Device by presenting a certificate IP address, to the Master Device by presenting a certificate
containing that identifier as a "subjectAltName" (i.e., as a dNSName containing that identifier as a "subjectAltName" (i.e., as a dNSName
or IP address). If the Master Device has external information as to or IP address). If the Master Device has external information as to
the expected identity or credentials of the proper database (e.g., a the expected identity or credentials of the proper database (e.g., a
certificate fingerprint), these checks MAY be omitted. Note that in certificate fingerprint), these checks MAY be omitted. Note that in
order for the presented certificate to be valid at the client, the order for the presented certificate to be valid at the client, the
client must be able to validate the certificate. In particular, the client must be able to validate the certificate. In particular, the
validation path of the certificate must end in one of the client's validation path of the certificate must end in one of the client's
trust anchors, even if that trust anchor is the Database certificate trust anchors, even if that trust anchor is the Database certificate
itself. [Editor's note: a database can change certificate itself. A Master Device should allow for the fact that a Database
authorities (CAs) over time. Should there be a recommendation about can change its certificate authorities (CAs) over time.
not relying on a single, statically configured CA certificate in the
Master Device?]
10.2. Protection Against Modification 10.2. Protection Against Modification
To prevent a PAWS response message from being modified en route, To prevent a PAWS response message from being modified en route,
messages must be transmitted over an integrity-protected channel. messages must be transmitted over an integrity-protected channel.
Using HTTP over TLS, the channel will be protected by appropriate Using HTTP over TLS, the channel will be protected by appropriate
cyphersuites. cyphersuites.
10.3. Protection Against Eavesdropping 10.3. Protection Against Eavesdropping
skipping to change at page 68, line 47 skipping to change at page 75, line 40
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
[RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig,
"Transport Layer Security (TLS) Session Resumption without "Transport Layer Security (TLS) Session Resumption without
Server-Side State", RFC 5077, January 2008. Server-Side State", RFC 5077, January 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV [RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV
Presence Information Data Format Location Object (PIDF-LO) Presence Information Data Format Location Object (PIDF-LO)
Usage Clarification, Considerations, and Recommendations", Usage Clarification, Considerations, and Recommendations",
RFC 5491, March 2009. RFC 5491, March 2009.
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
August 2011. August 2011.
skipping to change at page 70, line 7 skipping to change at page 77, line 7
"JSON-RPC 2.0 Specification", "JSON-RPC 2.0 Specification",
<http://www.jsonrpc.org/specification>. <http://www.jsonrpc.org/specification>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
Appendix A. Changes / Author Notes. Appendix A. Changes / Author Notes.
Notes: Changed from 01:
o Change needed: maxValidityTime in RulesetInfo doesn't work for US/ o Added a description of message sequences to support multiple rule
FCC, since the rule indicates 11:59 of following day (no timezone sets and multiple jurisdictions Section 3.1.
specified), which cannot be expressed as a duration o Modified DeviceDescriptor (Section 5.2) to add rulesetIds
parameter
o Modified RulesetInfo (Section 5.6), AvailableSpectrumResponse
(Section 4.4.2) to add rulesetId parameter.
o Add Extensibility (Section 8) section.
o Filled in IANA (Section 9) section.
o Removed blank Example Messages section
Changes from 00: Changes from 00:
o Add JSON encoding o Add JSON encoding
o Adopt RFC5491 for GeoLocation o Adopt RFC5491 for GeoLocation
o Adopt vCard for contact information o Adopt vCard for contact information
o Add Response Code section and update text referencing the defined o Add Response Code section and update text referencing the defined
response codes response codes
o Change DeviceIdentifier to be DeviceDescriptor, allowing o Change DeviceIdentifier to be DeviceDescriptor, allowing
identifiers and device-characteristic fields to be included. identifiers and device-characteristic fields to be included.
Appendix B. Regulatory-specific Notes
This section contains regualtory-specific details that should be
moved to other documents.
B.1. US / FCC
Device Registration
o The "antenna" parameter is REQUIRED for FIXED device types. It
MUST specify the antenna height the and height type.
o The "owner" parameter is REQUIRED for FIXED device types and if
the Device has not been registered yet with the Database or if the
Database does not implement a separate device registration
request.
Device Identifier
o The authority value MUST be "US"
o The identity value is the Device's FCC ID
o The "deviceType" parameter is REQUIRED to indicate the device
type. Valid values are FIXED, MODE_1, MODE_2
Antenna Height
o The height and heightType parameters are REQUIRED for FIXED device
types.
RuleSet Info
o "authority" MUST be the string, "US"
o "maxLocationChange" MUST be 50 meters
o "maxPollingSecs" MUST be 86400 seconds, corresponding to 24 hours
o "maxValiditySecs" MUST be 172800 seconds, corresponding to 48
hours
B.2. UK / Ofcom
Device Identifier
o The authority value MUST be "UK"
o The "RAT" parameter is required to specify the Radio Access
Technology. Valid values are TBD.
o A "deviceClass" parameter is required to identify, among other
things, the emission mask of the Device. Valid values are TBD.
GeoLocation
o Requires uncertainty in the X (longitude) and Y (latitude)
directions
Authors' Addresses Authors' Addresses
Vincent Chen (editor) Vincent Chen (editor)
Google Google
1600 Amphitheatre Parkway 1600 Amphitheatre Parkway
Mountain View, CA 94043 Mountain View, CA 94043
US US
Email: vchen@google.com Email: vchen@google.com
skipping to change at page 72, line 5 skipping to change at page 78, line 5
Applied Communication Sciences Applied Communication Sciences
444 Hoes Lane 444 Hoes Lane
Piscataway, NJ 08854 Piscataway, NJ 08854
U.S.A. U.S.A.
Phone: Phone:
Fax: Fax:
Email: sdas at appcomsci dot com Email: sdas at appcomsci dot com
URI: URI:
Zhu Lei Lei Zhu
Huawei Huawei
Phone: +86 13910157020 Phone: +86 13910157020
Fax: Fax:
Email: lei.zhu@huawei.com Email: lei.zhu@huawei.com
URI: URI:
John Malyar John Malyar
Telcordia Technologies Inc. Telcordia Technologies Inc.
1 Ericsson Drive 1 Ericsson Drive
 End of changes. 54 change blocks. 
238 lines changed or deleted 489 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/