idnits 2.17.1 draft-ietf-paws-protocol-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 8 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 6 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 11, 2014) is 3454 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-11) exists of draft-ietf-uta-tls-bcp-06 -- Possible downref: Non-RFC (?) normative reference: ref. 'JSON-RPC' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5077 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 PAWS V. Chen, Ed. 3 Internet-Draft Google 4 Intended status: Standards Track S. Das 5 Expires: May 15, 2015 Applied Communication Sciences 6 L. Zhu 7 Huawei 8 J. Malyar 9 iconectiv 10 P. McCann 11 Huawei 12 November 11, 2014 14 Protocol to Access White-Space (PAWS) Databases 15 draft-ietf-paws-protocol-20 17 Abstract 19 Portions of the radio spectrum that are allocated to licensees are 20 available for non-interfering use. This available spectrum is called 21 "White Space." Allowing secondary users access to available spectrum 22 "unlocks" existing spectrum to maximize its utilization and to 23 provide opportunities for innovation, resulting in greater overall 24 spectrum utilization. 26 One approach to managing spectrum sharing uses databases to report 27 spectrum availability to devices. To achieve interoperability among 28 multiple devices and databases, a standardized protocol must be 29 defined and implemented. This document defines such a protocol, the 30 "Protocol to Access White Space (PAWS) Databases". 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on May 15, 2015. 49 Copyright Notice 51 Copyright (c) 2014 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 67 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4 68 2.1. Conventions Used in This Document . . . . . . . . . . . . 5 69 2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 70 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 71 3.1. Multi-ruleset Support . . . . . . . . . . . . . . . . . . 7 72 4. Protocol Functionalities . . . . . . . . . . . . . . . . . . 8 73 4.1. Database Discovery . . . . . . . . . . . . . . . . . . . 10 74 4.2. PAWS Version . . . . . . . . . . . . . . . . . . . . . . 11 75 4.3. Initialization . . . . . . . . . . . . . . . . . . . . . 11 76 4.3.1. INIT_REQ . . . . . . . . . . . . . . . . . . . . . . 12 77 4.3.2. INIT_RESP . . . . . . . . . . . . . . . . . . . . . . 13 78 4.4. Device Registration . . . . . . . . . . . . . . . . . . . 14 79 4.4.1. REGISTRATION_REQ . . . . . . . . . . . . . . . . . . 15 80 4.4.2. REGISTRATION_RESP . . . . . . . . . . . . . . . . . . 15 81 4.5. Available Spectrum Query . . . . . . . . . . . . . . . . 16 82 4.5.1. AVAIL_SPECTRUM_REQ . . . . . . . . . . . . . . . . . 19 83 4.5.2. AVAIL_SPECTRUM_RESP . . . . . . . . . . . . . . . . . 21 84 4.5.3. AVAIL_SPECTRUM_BATCH_REQ . . . . . . . . . . . . . . 24 85 4.5.4. AVAIL_SPECTRUM_BATCH_RESP . . . . . . . . . . . . . . 27 86 4.5.5. SPECTRUM_USE_NOTIFY . . . . . . . . . . . . . . . . . 28 87 4.5.6. SPECTRUM_USE_RESP . . . . . . . . . . . . . . . . . . 29 88 4.6. Device Validation . . . . . . . . . . . . . . . . . . . . 30 89 4.6.1. DEV_VALID_REQ . . . . . . . . . . . . . . . . . . . . 31 90 4.6.2. DEV_VALID_RESP . . . . . . . . . . . . . . . . . . . 32 91 5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 32 92 5.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . . . 32 93 5.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . . 35 94 5.3. AntennaCharacteristics . . . . . . . . . . . . . . . . . 36 95 5.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . . 37 96 5.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . . . 37 97 5.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . . . 38 98 5.7. DbUpdateSpec . . . . . . . . . . . . . . . . . . . . . . 39 99 5.8. DatabaseSpec . . . . . . . . . . . . . . . . . . . . . . 40 100 5.9. SpectrumSpec . . . . . . . . . . . . . . . . . . . . . . 40 101 5.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . . 42 102 5.11. Spectrum . . . . . . . . . . . . . . . . . . . . . . . . 42 103 5.12. SpectrumProfile . . . . . . . . . . . . . . . . . . . . . 46 104 5.13. FrequencyRange . . . . . . . . . . . . . . . . . . . . . 47 105 5.14. EventTime . . . . . . . . . . . . . . . . . . . . . . . . 48 106 5.15. GeoSpectrumSpec . . . . . . . . . . . . . . . . . . . . . 48 107 5.16. DeviceValidity . . . . . . . . . . . . . . . . . . . . . 49 108 5.17. Error Element . . . . . . . . . . . . . . . . . . . . . . 50 109 5.17.1. OUTSIDE_COVERAGE Error . . . . . . . . . . . . . . . 52 110 5.17.2. DATABASE_CHANGE Error . . . . . . . . . . . . . . . 52 111 5.17.3. MISSING Error . . . . . . . . . . . . . . . . . . . 52 112 6. Message Encoding . . . . . . . . . . . . . . . . . . . . . . 53 113 6.1. JSON-RPC Binding . . . . . . . . . . . . . . . . . . . . 53 114 6.1.1. Method Names . . . . . . . . . . . . . . . . . . . . 55 115 6.1.2. JSON Encoding of Data Models . . . . . . . . . . . . 55 116 6.2. Example Encoding: spectrum.paws.init Method . . . . . . . 56 117 6.3. Example Encoding: spectrum.paws.getSpectrum Method . . . 57 118 6.4. Example Encoding: DeviceOwner vCard . . . . . . . . . . . 61 119 7. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . . . 61 120 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 63 121 8.1. Defining Ruleset Identifiers . . . . . . . . . . . . . . 63 122 8.2. Defining New Message Parameters . . . . . . . . . . . . . 64 123 8.3. Defining Additional Error Codes . . . . . . . . . . . . . 64 124 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 64 125 9.1. PAWS Ruleset ID Registry . . . . . . . . . . . . . . . . 65 126 9.1.1. Registration Template . . . . . . . . . . . . . . . . 65 127 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 67 128 9.2. PAWS Parameters Registry . . . . . . . . . . . . . . . . 73 129 9.2.1. Registration Template . . . . . . . . . . . . . . . . 73 130 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 73 131 9.3. PAWS Error Code Registry . . . . . . . . . . . . . . . . 75 132 9.3.1. Registration Template . . . . . . . . . . . . . . . . 76 133 9.3.2. Initial Registry Contents . . . . . . . . . . . . . . 76 134 10. Security Considerations . . . . . . . . . . . . . . . . . . . 76 135 10.1. Assurance of Proper Database . . . . . . . . . . . . . . 78 136 10.2. Protection Against Modification . . . . . . . . . . . . 79 137 10.3. Protection Against Eavesdropping . . . . . . . . . . . . 79 138 10.4. Client Authentication Considerations . . . . . . . . . . 79 139 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 80 140 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 80 141 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 80 142 13.1. Normative References . . . . . . . . . . . . . . . . . . 80 143 13.2. Informative References . . . . . . . . . . . . . . . . . 81 144 Appendix A. Database Listing Server Support . . . . . . . . . . 82 145 Appendix B. Changes / Author Notes. . . . . . . . . . . . . . . 83 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 91 148 1. Introduction 150 [RFC Editor: In the Author's Addresses section, please list 151 "iconectiv" as "iconectiv (formerly Telcordia Interconnection 152 Solutions). One occurrence."] 154 This section provides some high level introductory material. Readers 155 are strongly encouraged to read "Protocol to Access White-Space 156 (PAWS) Databases: Use Cases and Requirements" [RFC6953] for use 157 cases, requirements, and additional background. 159 A geospatial database can track available spectrum (in accordance 160 with the rules of one or more regulatory domains) and make this 161 information available to devices. This approach shifts the 162 complexity of spectrum-policy conformance out of the device and into 163 the database. This approach also simplifies adoption of policy 164 changes, limiting updates to a handful of databases, rather than 165 numerous devices. It opens the door for innovations in spectrum 166 management that can incorporate a variety of parameters, including 167 user location and time. In the future, it also can include other 168 parameters, such as user priority, signal type and power, spectrum 169 supply and demand, payment or micro-auction bidding, and more. 171 In providing this service, a database records and updates information 172 necessary to protect primary users -- for example, this information 173 may include parameters such as a fixed transmitter's call sign, its 174 geolocation, antenna height, power, and periods of operation. The 175 rules that the database is required to follow, including its schedule 176 for obtaining and updating protection information, protection rules, 177 and information reported to devices, vary according to regulatory 178 domain. Such variations, however, should be handled by each 179 database, and hidden from devices to the maximum extent possible. 181 This specification defines an extensible protocol, built on top of 182 HTTP and TLS, to obtain available spectrum from a geospatial database 183 by a device with geolocation capability. It enables a device to 184 operate in a regulatory domain that implements this protocol and 185 within which the device operates. 187 2. Conventions and Terminology 188 2.1. Conventions Used in This Document 190 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 191 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 192 document are to be interpreted as described in "Key words for use in 193 RFCs to Indicate Requirement Levels" [RFC2119]. 195 2.2. Terminology 197 Database or Spectrum Database: A database is an entity that contains 198 current information about available spectrum at a given location 199 and time, as well as other types of information related to 200 spectrum availability and usage. 202 Device ID: An identifier for a device. 204 EIRP: Effective isotropically radiated power 206 ETSI: European Telecommunications Standards Institute 207 (http://www.etsi.org) 209 FCC: The U.S. Federal Communications Commission 210 (http://www.fcc.gov) 212 Listing server: A server that provides the URIs for one or more 213 Spectrum Databases. A regulator, for example, may operate a 214 Database Listing Server to publish the list of authorized Spectrum 215 Databases for its regulatory domain. 217 Master Device: A device that queries the database, on its own behalf 218 and/or on behalf of a slave device, to obtain available spectrum 219 information. 221 Regulatory Domain: A location where certain rules apply to the use 222 of white space spectrum, including the operation of databases and 223 devices involved in its use. A regulatory domain is normally 224 defined by a unit of government for a particular country, but PAWS 225 is agnostic as to how a regulatory domain is constructed. 227 Ruleset: A ruleset represents a set of rules that governs the 228 operation of white space devices and Spectrum Databases. A 229 regulatory authority can define its own set of rules or adopt an 230 existing ruleset. When a Database or device is said to "support a 231 ruleset", it means that it contains out-of-band knowledge of the 232 rules and that its hardware and software implementations conform 233 to those rules. 235 Ruleset Identifier: A ruleset can be identified by an IANA- 236 registered identifier (see PAWS Ruleset ID Registry 237 (Section 9.1)). When a Database or device indicates it supports a 238 ruleset identifier, it means that it conforms to the rules 239 associated with that identifier. A regulatory authority can 240 define and register its own ruleset identifiers, or it can use a 241 previously registered identifier if it adopts an existing ruleset. 243 Slave Device: A device that queries the database through a master 244 device. 246 3. Protocol Overview 248 A Master Device uses PAWS to obtain a schedule of available spectrum 249 at its location. The security necessary to ensure the accuracy, 250 privacy, and confidentiality of the device's location is described in 251 the Security Considerations (Section 10). This document assumes that 252 the Master Device and the Database are connected to the Internet. 254 A typical sequence of PAWS operations is outlined as follows. See 255 Protocol Functionalities (Section 4) and Protocol Parameters 256 (Section 5) for details: 258 1. The Master Device obtains (statically or dynamically) the URI 259 for a Database appropriate for its location, to which to send 260 subsequent PAWS messages. 262 2. The Master Device establishes an HTTPS session with the 263 Database. 265 3. The Master Device optionally sends an initialization message to 266 the Database to exchange capabilities. 268 4. If the Database receives an initialization message, it responds 269 with an initialization-response message in the body of the HTTP 270 response. 272 5. The Database may require the Master Device to be registered 273 before providing service. 275 6. The Master Device sends an available-spectrum request message to 276 the Database. The message may be on behalf of a Slave Device 277 that made a request to the Master Device. 279 7. If the Master Device is making a request on behalf of a Slave 280 Device, the Master Device may verify with the Database that the 281 Slave Device is permitted to operate. 283 8. The Database responds with an available-spectrum response 284 message in the body of the HTTP response. 286 9. The Master Device may send a spectrum-usage notification message 287 to the Database. The notification is purely informational for 288 notifying the Database what spectrum it intends to use and is 289 not a request to the Database to get permission to use that 290 spectrum. Some databases may require spectrum-usage 291 notification. 293 10. If the Database receives a spectrum-usage notification message, 294 it responds by sending the Master Device a spectrum-usage 295 acknowledgement message. Since the notification is purely 296 informational, the Master Device does not need to process the 297 Database response. 299 Different regulatory domains may impose particular requirements, such 300 as requiring Master Devices to register with the Database, performing 301 Slave Device verification, and sending spectrum usage notifications. 303 3.1. Multi-ruleset Support 305 For a Master Device that supports multiple rulesets and operates with 306 multiple databases, PAWS supports the following sequence of 307 operations for each request by the Master Device: 309 1. The Master Device includes in its request its location and 310 optionally includes the identifier of all the rulesets it 311 supports and any parameter values it might need for the request 313 2. The Database uses the device location and also may use the 314 ruleset list to determine its response, for example, to select 315 the list of required parameters 317 3. If required parameters are missing from the request, the Database 318 responds with an error and a list of names of the missing 319 parameters 321 4. The Master Device makes the request again, adding the missing 322 parameter values 324 5. The Database responds to the request, including the identifier of 325 the applicable ruleset 327 6. The Master Device uses the indicated ruleset to determine how to 328 interpret the Database response 330 NOTE Some regulatory domains specify sets of requirements for device 331 behavior that may be complex and not easily parameterized. The 332 ruleset-id parameter provides a mechanism for the Database to inform 333 the Master Device of an applicable ruleset, and, for devices with 334 out-of-band knowledge of the particular regulatory domain 335 requirements, to satisfy those requirements without having to specify 336 the device-side behavior within the protocol. Ruleset identifiers 337 will normally contain the name of the regulatory body that 338 established the rules and version information, such as 339 "FccTvBandWhiteSpace-2010". 341 By separating the regulatory "authority" from the "ruleset-id", it 342 allows the protocol to support multiple regulatory authorities that 343 use the same device-side ruleset. It also allows support for a 344 single authority to define multiple rulesets. 346 4. Protocol Functionalities 348 PAWS consists of several components. As noted below, some regulatory 349 domains or Database implementations may mandate the use of a 350 component, even when its use is not mandated by PAWS. 352 o Database Discovery (Section 4.1) is a required component for the 353 Master Device. 355 o Initialization (Section 4.3) is a required component for the 356 Database. Its use allows the Master Device to determine necessary 357 information that have not been preconfigured. 359 o Device Registration (Section 4.4) is an optional component for the 360 Database. It can be implemented as a separate component or as 361 part of the Available Spectrum Query (Section 4.5) component. It 362 is used by the Master Device when the Database requires it. Note 363 that some regulators require device registration for only specific 364 device types, such as higher-power fixed (as opposed to mobile) 365 devices to allow them to contact the operators to resolve any 366 interference issues. 368 o Available Spectrum Query (Section 4.5) is a required component for 369 the Master Device and the Database. 371 o Spectrum Use Notify (Section 4.5.5) is an optional component for 372 the Master Device and the Database. When it is required, the 373 Database informs the Master Device via its response to the 374 Available Spectrum Query (Section 4.5). 376 o Device Validation (Section 4.6) as a separate component is 377 optional for the Master Device and Database. When implemented by 378 the Database, its use allows the Master Device to validate Slave 379 Devices without having to use the full Available Spectrum Query. 381 This section describes the protocol components and their messages. 382 Protocol Parameters (Section 5) contains a more thorough discussion 383 of the parameters that make up the PAWS request and response 384 messages. Message Encoding (Section 6) provides examples of message 385 encodings. HTTPS Binding (Section 7) describes the use of HTTPS 386 ("HTTP Over TLS" [RFC2818]) for transferring PAWS messages and 387 optional device authentication. 389 The parameter tables in this section and Protocol Parameters 390 (Section 5) are for reference and contain the name of each parameter, 391 the data type of each parameter, and whether the existence of the 392 parameter is required for the protocol transaction in question. The 393 diagrams are loosely based on UML, and the data types are defined 394 either in Protocol Parameters (Section 5) or are one of the following 395 primitive or structured types: 397 string: A string, as defined by JSON [RFC7159], restricted to the 398 UTF-8 encoding. 400 int: A number, as defined by JSON [RFC7159], without a fractional or 401 exponent part. 403 float: A number, as defined by JSON [RFC7159]. 405 boolean: A boolean, as defined by JSON [RFC7159]. 407 list: A structured type that represents a list of elements, as 408 defined by JSON [RFC7159] array type. All elements of the list 409 are of the same data type, which is indicated in its diagram and 410 description. The diagram notation and description may include 411 additional constraints, such as minimum or maximum number of 412 elements. 414 Also: 416 o All parameter names are case sensitive. Unless stated otherwise, 417 all string values are case sensitive. 419 o All timestamps are in UTC and are expressed using exactly the 420 form, YYYY-MM-DDThh:mm:ssZ, as defined by "Date and Time on the 421 Internet: Timestamps" [RFC3339]. 423 In some cases, specific rulesets may place additional requirements on 424 message parameters. These additional requirements will be documented 425 in the IANA PAWS Ruleset ID Registry. (Section 9.1). When a request 426 message sent to the Database has missing parameters, whether they are 427 required by PAWS or the applicable ruleset, the Database returns the 428 MISSING (Section 5.17.3) error, along with data indicating the 429 missing parameters. 431 4.1. Database Discovery 433 Preconfiguration 435 The Master Device can be provisioned statically (preconfigured) with 436 the URI of one or more Databases. For example, in a particular 437 regulatory domain, there may be a number of certified Databases that 438 any device operating in that domain is permitted to connect to, and 439 those URIs can be preconfigured in the device. 441 Listing Server Support: As an alternative to preconfiguring devices 442 with a list of certified Databases, some regulatory domains support 443 the preconfiguration of devices with the URI of a certified listing 444 server, to which devices can connect to obtain the list of certified 445 Databases. See Listing Server Support (Appendix A) for further 446 information. 448 Configuration Update: Database URI changes 450 To adapt to changes in the list of certified or approved databases, 451 the device needs to update its preconfigured list of databases. 453 A Database MAY change its URI, but before it changes its URI, it MUST 454 indicate so by including the URI of one or more alternate databases 455 using DbUpdateSpec (Section 5.7) in its responses to devices. The 456 Database MUST reply with DbUpdateSpec for a minimum of 2 weeks before 457 disabling the old URI. A device will update its preconfigured entry 458 for the Database sending the DbUpdateSpec by replacing this entry 459 with the alternate databases listed in the DbUpdateSpec; the list of 460 alternate databases does not affect any other entries. Note that the 461 ordering of databases in the list does not imply any preference and 462 does not need to remain the same for every request. The device 463 SHOULD detect infinite redirection loops; if a suitable database 464 cannot be contacted, the device MUST treat this as equivalent to a 465 response indicating no available spectrum. This database-change 466 mechanism is used, for example, before a Database ceases operation; 467 it is not intended to be used for dynamic load balancing. 469 Error Handling 471 The device SHOULD select another database from its list of 472 preconfigured databases if: 474 o The selected database is unreachable or does not respond. 476 o The selected database returns an UNSUPPORTED error (see Error 477 Codes (Section 5.17)), which indicates the database does not 478 support the device (based on its device type, model, etc.) or 479 supports none of the rulesets specified in the request. 481 If a suitable database cannot be contacted, the device MUST treat 482 this as equivalent to a response indicating no available spectrum. 483 If the device had previously contacted a database to get available 484 spectrum, but subsequently fails to contact a suitable database, the 485 spectrum the device is currently using can be used for as long as the 486 spectrum data is valid; but after that period, the device will no 487 longer have valid spectrum to use. Some regulatory domains may have 488 specific rules regarding how long the spectrum data remains valid in 489 these cases. 491 4.2. PAWS Version 493 PAWS version uses a "." numbering scheme to indicate 494 versions of the protocol. The protocol versioning policy is intended 495 to allow the device or Database to indicate the format of a message 496 and its understanding of PAWS functionality defined by that version. 497 No change is made to the version string for the addition of message 498 components which only add to extensible parameter values. The 499 number is incremented when the changes made to the protocol 500 add functionalities (methods), but do not change the existing 501 functionalities. The number is incremented when incompatible 502 changes are made to existing functionality. 504 The current PAWS version is "1.0". 506 4.3. Initialization 508 A Master Device SHOULD use the initialization procedure to exchange 509 capability information with the Database whenever the Master Device 510 powers up or initiates communication with the Database. The 511 initialization response informs the Master Device of specific 512 parameterized-rule values for each supported ruleset, such as 513 threshold distances and time periods beyond which the device must 514 update its available-spectrum data (see RuleSetInfo (Section 5.6)). 515 When parameterized-rule values are not preconfigured for the 516 applicable ruleset at the specified location, a Master Device MUST 517 use the initialization procedure. 519 It is important to note that, when parameterized-rule values are 520 preconfigured in a Master Device, they are preconfigured on a per- 521 ruleset basis. That is, values preconfigured for one ruleset is not 522 applicable to any other ruleset. 524 For database implementations that require it, the initialization 525 message also enables extra database-specific or ruleset-specific 526 handshake parameters to be communicated before allowing available- 527 spectrum requests. 529 The Initialization request procedure is depicted in Figure 1. 531 o INIT_REQ (Section 4.3.1) is the initialization request message 533 o INIT_RESP (Section 4.3.2) is the initialization response message 535 +---------------+ +-------------------+ 536 | Master Device | | Spectrum Database | 537 +---------------+ +-------------------+ 538 | | 539 | INIT_REQ | 540 |-------------------->| 541 | | 542 | INIT_RESP | 543 |<--------------------| 544 | | 546 Figure 1 548 4.3.1. INIT_REQ 550 The initialization request message allows the Master Device to 551 initiate exchange of capabilities with the Database. 553 +---------------------------------------+ 554 |INIT_REQ | 555 +----------------------------+----------| 556 |deviceDesc:DeviceDescriptor | required | 557 |location:GeoLocation | required | 558 |.......................................| 559 |*other:any | optional | 560 +----------------------------+----------+ 562 Parameters: 564 deviceDesc: The DeviceDescriptor (Section 5.2) for the device is 565 REQUIRED. If the device descriptor does not contain any ruleset 566 IDs, the Master Device is asking the Database to return a 567 RulesetInfo (Section 5.6) list that specifies the rulesets that it 568 supports at the specified location. 570 location: The GeoLocation (Section 5.1) of the device is REQUIRED. 571 If the location is outside all regulatory domain supported by the 572 Database, the Database MUST respond with an OUTSIDE_COVERAGE 573 (Table 1) error. 575 other: The Master Device MAY specify additional handshake parameters 576 in the INIT_REQ message. The Database MUST ignore all parameters 577 it does not understand. To simplify its initialization logic, a 578 Master Device that supports multiple Databases and rulesets can 579 include the union of all required parameters for all its supported 580 rulesets. Consult the PAWS Parameters Registry (Section 9.2) for 581 possible additional parameters. 583 4.3.2. INIT_RESP 585 The initialization response message communicates database parameters 586 to the requesting device. This response is returned only when there 587 is at least one ruleset. Otherwise, the Database returns an error 588 response, as described in INIT_REQ (Section 4.3.1). 590 +---------------------------------------+ 591 |INIT_RESP | 592 +----------------------------+----------+ 1..* +-------------+ 593 |rulesetInfos:list | required |------->| RulesetInfo | 594 |databaseChange:DbUpdateSpec | optional | +-------------+ 595 |.......................................| 596 |*other:any | optional | 597 +----------------------------+----------+ 599 Parameters: 601 rulesetInfos: A RulesetInfo (Section 5.6) list MUST be included in 602 the response. Each RulesetInfo corresponds to a ruleset supported 603 by the Database and is applicable to the location specified in the 604 INIT_REQ (Section 4.3.1) message. 606 If the device included a list of ruleset IDs in the 607 DeviceDescriptor of its INIT_REQ message, each RulesetInfo in the 608 response MUST match one of the specified ruleset IDs. 610 If the DeviceDescriptor did not contain any ruleset IDs, the 611 Database SHOULD include in the rulesetInfos list a RulesetInfo for 612 each ruleset it supports at the specified location. 614 If the Database does not support the device or supports none of 615 the rulesets specified in the DeviceDescriptor, it MUST instead 616 return an error with the UNSUPPORTED (Table 1) code in the error 617 response. 619 databaseChange: The Database MAY include a DbUpdateSpec 620 (Section 5.7) to notify the Master Device of a change to the 621 Database URI, providing one or more alternate database URIs. The 622 device needs to update its preconfigured entry for the responding 623 database with the alternate databases listed in the DbUpdateSpec. 625 other: The Database MAY include additional handshake parameters in 626 the INIT_RESP (Section 4.3.2) message. The Master Device MUST 627 ignore all parameters it does not understand. Consult the PAWS 628 Parameters Registry (Section 9.2) for possible additional 629 parameters. 631 4.4. Device Registration 633 Some rulesets require a Master Device to send its registration 634 information to the Database in order to establish certain operational 635 parameters. FCC rules, for example, require that a 'Fixed Device' 636 register its owner and operator contact information, its device 637 identifier, its location, and its antenna height (see FCC CFR47-15H 638 [FCC-CFR47-15H]). 640 The Database MAY implement device registration as a separate Device 641 Registration request, or as part of the Spectrum Availability 642 request. If the Database does not implement a separate Device 643 Registration request, it MUST return an error with the UNIMPLEMENTED 644 (Table 1) code in the error-response message. 646 The Device Registration request procedure is depicted in Figure 2. 648 o REGISTRATION_REQ (Section 4.4.1) is the device-registration 649 request message 651 o REGISTRATION_RESP (Section 4.4.2) is the device-registration 652 response message 654 +---------------+ +-------------------+ 655 | Master Device | | Spectrum Database | 656 +---------------+ +-------------------+ 657 | | 658 | REGISTRATION_REQ | 659 |------------------------>| 660 | | 661 | REGISTRATION_RESP | 662 |<------------------------| 663 | | 665 Figure 2 667 4.4.1. REGISTRATION_REQ 669 The registration request message contains the required registration 670 parameters. A parameter marked as optional may be required by some 671 rulesets. 673 +-------------------------------------------+ 674 |REGISTRATION_REQ | 675 +-------------------------------+-----------+ 676 |deviceDesc:DeviceDescriptor | required | 677 |location:GeoLocation | required | 678 |deviceOwner:DeviceOwner | optional | 679 |antenna:AntennaCharacteristics | optional | 680 |...........................................| 681 |*other:any | optional | 682 +-------------------------------+-----------+ 684 Parameters: 686 deviceDesc: The DeviceDescriptor (Section 5.2) for the Master Device 687 is REQUIRED. The ruleset IDs included in the DeviceDescriptor 688 indicate the rulesets for which the device wishes to register. 690 location: The GeoLocation (Section 5.1) for the device is REQUIRED. 691 More precisely, this is the location at which the device intends 692 to operate. If the location is outside all regulatory domains 693 supported by the Database, the Database MUST respond with an 694 OUTSIDE_COVERAGE (Table 1) error. 696 deviceOwner: The DeviceOwner (Section 5.5) information is OPTIONAL. 697 Some rulesets may require deviceOwner information under certain 698 conditions. See PAWS Ruleset ID Registry (Section 9.1) for 699 ruleset-specific requirements. 701 antenna: The AntennaCharacteristics (Section 5.3) is OPTIONAL. 703 other: Rulesets and database implementations may require additional 704 registration parameters. To simplify its registration logic, the 705 Master Device MAY send a union of the registration information 706 required by all supported rulesets. The Database MUST ignore all 707 parameters it does not understand. Consult the PAWS Parameters 708 Registry (Section 9.2) for possible additional parameters. 710 4.4.2. REGISTRATION_RESP 712 The registration response message acknowledges successful 713 registration by including a RulesetInfo message for each ruleset in 714 which the registration is accepted. If the Database accepts the 715 registration for none of the specified rulesets, the Database MUST 716 return the NOT_REGISTERED error (See Error Codes (Section 5.17)). 718 +---------------------------------------+ 719 |REGISTRATION_RESP | 720 +----------------------------+----------+ 1..* +-------------+ 721 |rulesetInfos:list | required |------->| RulesetInfo | 722 |databaseChange:DbUpdateSpec | optional | +-------------+ 723 |............................|..........| 724 |*other:any | optional | 725 +----------------------------+----------+ 727 Parameters: 729 rulesetInfos: A RulesetInfo (Section 5.6) list MUST be included in 730 the response. Each entry corresponds to a ruleset for which the 731 registration was accepted. The list MUST contain at least one 732 entry. 734 Each RulesetInfo in the response MUST match one of the ruleset IDs 735 specified in the DeviceDescriptor of REGISTRATION_REQ. 737 If the Database does not support the device or supports none of 738 the rulesets specified in the DeviceDescriptor, it MUST instead 739 return an error with the UNSUPPORTED (Table 1) code in the error 740 response. 742 databaseChange: The Database MAY include a DbUpdateSpec 743 (Section 5.7) to notify the Master Device of a change to the 744 Database URI, providing one or more alternate database URIs. The 745 device needs to update its preconfigured entry for the responding 746 database with the alternate databases listed in the DbUpdateSpec. 748 other: Database implementations MAY return additional parameters in 749 the registration response. The Master Device MUST ignore any 750 parameters it does not understand. Consult the PAWS Parameters 751 Registry (Section 9.2) for possible additional parameters. 753 4.5. Available Spectrum Query 755 To obtain the available spectrum from the Database, a Master Device 756 sends a request that contains its geolocation and any parameters 757 required by the ruleset (such as device identifier, capabilities, and 758 characteristics). The Database returns a response that describes 759 which frequencies are available, at what permissible operating power 760 levels, and a schedule of when they are available. 762 The Available Spectrum Query procedure is depicted in Figure 3. 764 o AVAIL_SPECTRUM_REQ (Section 4.5.1) is the available-spectrum 765 request message. 767 o AVAIL_SPECTRUM_RESP (Section 4.5.2) is the available-spectrum 768 response message. 770 o AVAIL_SPECTRUM_BATCH_REQ (Section 4.5.3) is an OPTIONAL batch 771 version of the available-spectrum request message that allows 772 multiple locations to be specified in the request. 774 o AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) is the response message 775 for the batch version of the available-spectrum request that 776 contains available spectrum for each location in the request. 778 o SPECTRUM_USE_NOTIFY (Section 4.5.5) is the spectrum-usage 779 notification message. 781 o SPECTRUM_USE_RESP (Section 4.5.6) is the spectrum-usage 782 acknowledgment message. 784 +---------------+ +-------------------+ 785 | Master Device | | Spectrum Database | 786 +---------------+ +-------------------+ 787 | | 788 | AVAIL_SPECTRUM_REQ | 789 | (AVAIL_SPECTRUM_BATCH_REQ) | 790 |--------------------------->| 791 | | 792 | AVAIL_SPECTRUM_RESP | 793 | (AVAIL_SPECTRUM_BATCH_RESP)| 794 |<---------------------------| 795 | | 796 | (SPECTRUM_USE_NOTIFY) | 797 |--------------------------->| 798 | | 799 | (SPECTRUM_USE_RESP) | 800 |<---------------------------| 801 | | 803 Figure 3 805 1. First, the Master Device sends an available-spectrum request 806 message to the Database. 808 2. The Database MUST respond with an error using the NOT_REGISTERED 809 (Table 1) code if: 811 * registration information is required, and 812 * the request does not include registration information, and 814 * the device has not previously registered with the Database 816 3. If the location specified in the request is outside the 817 regulatory domain supported by the Database, the Database MUST 818 respond with an OUTSIDE_COVERAGE (Table 1) error. If some, but 819 not all, locations within a batch request are outside the 820 regulatory domain supported by the Database, the Database MUST 821 return an OK response with available spectrum for only the valid 822 locations; otherwise, if all locations within a batch request are 823 outside the regulatory domain, the Database MUST respond with an 824 OUTSIDE_COVERAGE error. 826 4. The Database MAY perform other validation of the request, (e.g., 827 checking for missing required parameters, authorizations). If 828 validation fails, the Database returns an appropriate error code 829 (Table 1). If the request is missing required parameters, the 830 Database MUST respond with a MISSING (Table 1) error and SHOULD 831 include a list of the missing parameters. 833 5. If the request is valid, the Database responds with an available- 834 spectrum response message. If the ruleset requires that devices 835 must report anticipated spectrum usage, the Database will 836 indicate so in the response message. 838 6. If the available-spectrum response indicates that the Master 839 Device must send a spectrum-usage notification message, the 840 Master Device sends the notification message to the Database. 841 Even when not required by the database, the Master Device MAY 842 send a notification message. 844 7. If the Database receives a spectrum-usage notification message, 845 it MUST send a spectrum-usage acknowledgment message to the 846 Master Device. 848 The procedure for a Master Device asking for available spectrum on 849 behalf of a Slave Device is similar, except that the process is 850 initiated by the Slave Device. The device identifier, capabilities, 851 and characteristics communicated in the AVAIL_SPECTRUM_REQ message 852 MUST be those of the Slave Device, and: 854 o The "masterDeviceLocation" field specifying the location of the 855 Master Device is REQUIRED. 857 o The "location" field specifying the location of the Slave Device 858 is OPTIONAL, since the Slave Device may not have location-sensing 859 capabilities. 861 Although the communication and protocol between the Slave Device and 862 Master Device is outside the scope of this document (represented as 863 dotted lines), the expected message sequence is shown in Figure 4. 865 +------------+ +---------------+ +-------------------+ 866 |Slave Device| | Master Device | | Spectrum Database | 867 +------------+ +---------------+ +-------------------+ 868 | | | 869 | AVAIL_SPEC_REQ | | 870 |................>| | 871 | | | 872 | | AVAIL_SPECTRUM_REQ | 873 | |-------------------------->| 874 | | | 875 | | AVAIL_SPECTRUM_RESP | 876 | |<--------------------------| 877 | AVAIL_SPEC_RESP | | 878 |<................| | 879 | | | 880 | (SPECTRUM_USE) | | 881 |................>| (SPECTRUM_USE_NOTIFY) | 882 | |-------------------------->| 883 | | | 884 | | (SPECTRUM_USE_RESP) | 885 | |<--------------------------| 886 | | | 888 Figure 4 890 4.5.1. AVAIL_SPECTRUM_REQ 892 The request message for the Available Spectrum Query protocol MUST 893 include a geolocation. Rulesets may mandate that it be the device's 894 current location or allow it to be an anticipated location. A 895 parameter marked as optional may be required by some rulesets. 897 +----------------------------------------------------+ 898 |AVAIL_SPECTRUM_REQ | 899 +----------------------------------+-----------------+ 900 |deviceDesc:DeviceDescriptor | see description | 901 |location:GeoLocation | see description | 902 |owner:DeviceOwner | optional | 903 |antenna:AntennaCharacteristics | optional | 904 |capabilities:DeviceCapabilities | optional | 905 |masterDeviceDesc:DeviceDescriptor | optional | 906 |masterDeviceLocation:GeoLocation | see description | 907 |requestType:string | optional | 908 |..................................|.................| 909 |*other:any | optional | 910 +----------------------------------+-----------------+ 912 Parameters: 914 deviceDesc: The DeviceDescriptor (Section 5.2) for the device 915 requesting available spectrum. When the request is made by a 916 Master Device on its own behalf, the descriptor is that of the 917 Master Device and it is REQUIRED. When the request is made on 918 behalf of a Slave Device, the descriptor is that of the Slave 919 Device, and it is REQUIRED if the "requestType" parameter is not 920 specified. The deviceDesc parameter may be OPTIONAL for some 921 values of requestType. 923 location: The GeoLocation (Section 5.1) for the device requesting 924 available spectrum. More precisely, this is the location at which 925 the device intends to operate. When the request is made by the 926 Master Device on its own behalf, the location is that of the 927 Master Device and it is REQUIRED. When the request is made by the 928 Master Device on behalf of a Slave Device, the location is that of 929 the Slave Device, and it is OPTIONAL (see also 930 masterDeviceLocation). The location may be an anticipated 931 position of the device to support mobile devices, but its use 932 depends on the ruleset. If the location specifies a region, 933 rather than a point, the Database MAY return an error with the 934 UNIMPLEMENTED (Table 1) code, if it does not implement query by 935 region. 937 NOTE: Technically, this is the location of the radiation center of 938 the device's antenna, but that distinction may be relevant only 939 for fixed devices. 941 owner: The DeviceOwner (Section 5.5) information MAY be included to 942 register the device with the Database. This enables the device to 943 register and get spectrum-availability information in a single 944 request. Some rulesets mandate registration for specific device 945 types. 947 antenna: The AntennaCharacteristics (Section 5.3) is OPTIONAL. 949 capabilities: The Master Device MAY include its DeviceCapabilities 950 (Section 5.4) to limit the available-spectrum response to the 951 spectrum that is compatible with its capabilities. The Database 952 SHOULD NOT return spectrum that is not compatible with the 953 specified capabilities. 955 masterDeviceDesc: When the request is made by the Master Device on 956 behalf of a Slave Device, the Master Device MAY provide its own 957 descriptor. 959 masterDeviceLocation: When the request is made by the Master Device 960 on behalf of a Slave Device, the Master Device MUST provide its 961 own GeoLocation (Section 5.1). 963 requestType: The request type is OPTIONAL, which may be used to 964 modify the request, but its use depends on the applicable ruleset. 965 The request type may be used, for example, to indicate that the 966 response should include generic Slave Device parameters without 967 having to specify the device descriptor for a specific device. 968 When requestType is missing, the request is for a specific device 969 (Master or Slave), so deviceDesc is REQUIRED. The maximum length 970 of the value is 64 octets. See IANA Ruleset Registry, Initial 971 Registry Contents (Section 9.1.2) for ruleset specifics. 973 other: Rulesets and database implementations may require additional 974 request parameters. The Database MUST ignore all parameters it 975 does not understand. Consult the PAWS Parameters Registry 976 (Section 9.2) for possible additional parameters. 978 4.5.2. AVAIL_SPECTRUM_RESP 980 The response message for the Available Spectrum Query contains one or 981 more SpectrumSpec (Section 5.9) elements, one for each ruleset 982 supported at the location specified in the corresponding 983 AVAIL_SPECTRUM_REQ (Section 4.5.1) request. Each SpectrumSpec 984 element contains a list of one or more spectrum schedules, 985 representing permissible power levels over time: 987 o Each spectrum schedule specifies permissible power level for a 988 duration defined by a pair of start and stop times. The power 989 levels refer to permissible EIRP over a resolution bandwidth. 991 o Within each list of schedules, event-time intervals MUST be 992 disjoint and MUST be sorted in increasing time. 994 o A gap in the time schedule means no spectrum is available for that 995 time interval. 997 Consider a Database that provides a schedule of available spectrum 998 for the next 24 hours. If spectrum availability were to be different 999 at different times of day, the response would contain a list of 1000 schedules, each transition representing some change to the spectrum 1001 availability. A device might use different strategies to select 1002 which spectrum to use, e.g.: 1004 o Always use the frequencies that permit the highest power 1006 o Use the frequencies that is available for the longest period of 1007 time 1009 o Just use the first set of frequencies that matches its needs 1010 +---------------------------------------+ 1011 |AVAIL_SPECTRUM_RESP | 1012 +----------------------------+----------+ 1013 |timestamp:string | required | 1014 |deviceDesc:DeviceDescriptor | required | 1015 |spectrumSpecs:list | required |-------+ 1016 |............................|..........| | 1017 |databaseChange:DbUpdateSpec | optional | | 1018 |*other:any | optional | | 1019 +----------------------------+----------+ | 1..* 1020 V 1021 +-----------------------------------+ 1022 |SpectrumSpec | 1023 +------------------------+----------+ 1024 |rulesetInfo:RulesetInfo | required | 1025 |spectrumSchedules:list | required |-+ 1026 |timeRange:EventTime | optional | | 1027 |frequencyRanges:list | optional | | 1028 |needsSpectrumReport:bool| optional | | 1029 |maxTotalBwHz:float | optional | | 1030 |maxContiguousBwHz:float | optional | | 1031 +------------------------+----------+ | 1032 +--------------------+ 1033 | 1..* 1034 V 1035 +-------------------------------+ 1036 |SpectrumSchedule | 1037 +--------------------+----------+ 1038 |eventTime:EventTime | required | 1039 |spectra:list | required | 1040 +--------------------+----------+ 1042 Parameters: 1044 timestamp: Timestamp of the response is expressed in UTC using the 1045 form, YYYY-MM-DDThh:mm:ssZ, as defined by "Date and Time on the 1046 Internet: Timestamps" [RFC3339]. This can be used by the device 1047 as a reference for the start and stop times in the spectrum 1048 schedules. 1050 deviceDesc: The Database MUST include the DeviceDescriptor 1051 (Section 5.2) specified in the AVAIL_SPECTRUM_REQ message. 1053 spectrumSpecs: The SpectrumSpec (Section 5.9) list MUST include at 1054 least one entry. Each entry contains the schedules of available 1055 spectrum for a ruleset. The Database MAY return more than one 1056 SpectrumSpec to represent available spectrum for multiple rulesets 1057 at the specified location. 1059 databaseChange: The Database MAY include a DbUpdateSpec 1060 (Section 5.7) to notify the device of a change to the Database 1061 URI, providing one or more alternate database URIs. The device 1062 needs to update its preconfigured entry for the responding 1063 database with the alternate databases listed in the DbUpdateSpec. 1065 other: Database implementations MAY return additional parameters in 1066 the response. The device MUST ignore any parameters that it does 1067 not understand. Consult the PAWS Parameters Registry 1068 (Section 9.2) for possible additional parameters and requirements 1069 they place on the device. 1071 4.5.2.1. Update Requirements 1073 When the stop time specified in the schedule has been reached, the 1074 device: 1076 o MUST obtain a new spectrum-availability schedule, either by using 1077 the next one in the list (if provided) or making another Available 1078 Spectrum Query (Section 4.5). 1080 o If the device is unable to contact the Database to obtain a new 1081 schedule, it MUST treat this as equivalent to a response with no 1082 available spectrum. 1084 Some rulesets also mandate that a device must obtain a new specturm- 1085 availability schedule if the device moves beyond a threshold distance 1086 (established by the ruleset) away from the actual location and all 1087 anticipated location(s) it reported in previous AVAIL_SPECTRUM_REQ or 1088 AVAIL_SPECTRUM_BATCH_REQ requests (see "maxLocationChange" in 1089 RulesetInfo (Section 5.6)). If the device is unable to contact the 1090 Database to obtain a new schedule, it MUST treat this as equivalent 1091 to a response with no available spectrum. 1093 NOTE: The ruleset determines required device behavior when spectrum 1094 is no longer available. The ruleset also governs whether a device 1095 may request and use spectrum at anticipated locations beyond the 1096 threshold distance from its current location. 1098 4.5.3. AVAIL_SPECTRUM_BATCH_REQ 1100 The Database MAY implement the batch request that allows multiple 1101 locations to be specified. This enables a portable Master Device, 1102 for example, to get available spectrum for a sequence of anticipated 1103 locations using a single request. The Database interprets each 1104 location in the batch request as if it were an independent request 1105 and returns results consistent with multiple individual 1106 AVAIL_SPECTRUM_REQ (Section 4.5.1) requests, but returns these 1107 results in a batched response (Section 4.5.4). The request message 1108 for the batch Available Spectrum Query protocol MUST include at least 1109 one GeoLocation (Section 5.1). If the Database does not implement 1110 batch requests, it MUST return an UNIMPLEMENTED (Table 1) error. 1112 NOTE: Whether anticipated locations are allowed depends on the 1113 specified ruleset. A parameter marked as optional may be required by 1114 some rulesets. 1116 +---------------------------------------------------+ 1117 |AVAIL_SPECTRUM_BATCH_REQ | 1118 +---------------------------------+-----------------+ 1119 |deviceDesc:DeviceDescriptor | see description | 1120 |locations:list | required |--+ 1121 |owner:DeviceOwner | optional | | 1122 |antenna:AntennaCharacteristics | optional | | 1123 |capabilities:DeviceCapabilities | optional | | 1124 |masterDeviceDesc:DeviceDescriptor| optional | | 1125 |masterDeviceLocation:GeoLocation | see description | | 1126 |requestType:string | optional | | 1127 +.................................+.................+ | 1128 |*other:any | optional | | 1129 +---------------------------------+-----------------+ | 1130 | 1131 1..* V 1132 +-------------+ 1133 | GeoLocation | 1134 +-------------+ 1136 Parameters: 1138 deviceDesc: The DeviceDescriptor (Section 5.2) for the device 1139 requesting available spectrum. When the request is made by a 1140 Master Device on its own behalf, the descriptor is that of the 1141 Master Device and it is REQUIRED. When the request is made on 1142 behalf of a Slave Device, the descriptor is that of the Slave 1143 Device, and it is REQUIRED if the "requestType" parameter is not 1144 specified. The deviceDesc parameter may be OPTIONAL for some 1145 values of requestType. 1147 locations: The GeoLocation (Section 5.1) list for the device is 1148 REQUIRED. This allows the device to specify its actual location 1149 plus additional anticipated locations. At least one location MUST 1150 be included. This specification places no upper limit on the 1151 number of locations, but the Database MAY restrict the number of 1152 locations it supports by returning a response with fewer locations 1153 than specified in the request. If the locations specify regions, 1154 rather than points, the Database MAY return an error with the 1155 UNIMPLEMENTED (Table 1) code, if it does not implement query by 1156 region. When the request is made by a Master Device on its own 1157 behalf, the locations are those of the Master Device. When the 1158 request is made by the Master Device on behalf of a Slave Device, 1159 the locations are those of the Slave Device (see also 1160 masterDeviceLocation). 1162 owner: The DeviceOwner (Section 5.5) information MAY be included to 1163 register the device with the Database. This enables the device to 1164 register and get spectrum-availability information in a single 1165 request. Some rulesets mandate registration for specific device 1166 types. 1168 antenna: The AntennaCharacteristics (Section 5.3) is OPTIONAL. 1170 capabilities: The Master Device MAY include its DeviceCapabilities 1171 (Section 5.4) to limit the available-spectrum response to the 1172 spectrum that is compatible with its capabilities. The Database 1173 SHOULD NOT return spectrum that is not compatible with the 1174 specified capabilities. 1176 masterDeviceDesc: When the request is made by the Master Device on 1177 behalf of a Slave Device, the Master Device MAY provide its own 1178 descriptor. 1180 masterDeviceLocation: When the request is made by the Master Device 1181 on behalf of a Slave Device, the Master Device MUST provide its 1182 own GeoLocation (Section 5.1). 1184 requestType: The request type is an OPTIONAL parameter that may be 1185 used to modify the request, but its use depends on applicable the 1186 ruleset. The request type may be used, for example, to request 1187 generic Slave Device parameters without having to specify the 1188 device descriptor for a specific device. When the requestType 1189 parameter is missing, the request is for a specific device (Master 1190 or Slave), so deviceDesc is REQUIRED. The maximum length is 64 1191 octets. See IANA Ruleset Registry, Initial Registry Contents 1192 (Section 9.1.2) for ruleset specifics. 1194 other: Rulesets and database implementations may require additional 1195 request parameters. The Database MUST ignore all parameters it 1196 does not understand. Consult the PAWS Parameters Registry 1197 (Section 9.2) for possible additional parameters. 1199 4.5.4. AVAIL_SPECTRUM_BATCH_RESP 1201 The response message for the batch Available Spectrum Query contains 1202 a schedule of available spectrum for the device at multiple 1203 locations. 1205 +---------------------------------------+ 1206 |AVAIL_SPECTRUM_BATCH_RESP | 1207 +----------------------------+----------+ 1208 |timestamp:string | required | 1209 |deviceDesc:DeviceDescriptor | required | 1210 |geoSpectrumSpecs:list | required |-------+ 1211 |............................|..........| | 1212 |databaseChange:DbUpdateSpec | optional | | 1213 |*other:any | optional | | 1214 +----------------------------+----------+ | 0..* 1215 V 1216 +---------------------------------+ 1217 |GeoSpectrumSpec | 1218 +----------------------+----------+ 1219 |location:GeoLocation | required | 1220 |spectrumSpecs:list | required | 1221 +----------------------+----------+ 1223 Parameters: 1225 timestamp: Timestamp of the response of the form, YYYY-MM- 1226 DDThh:mm:ssZ, as defined by "Date and Time on the Internet: 1227 Timestamps" [RFC3339]. This can be used by the device as a 1228 reference for the start and stop times in the spectrum schedules. 1230 deviceDesc: The Database MUST include the DeviceDescriptor 1231 (Section 5.2) specified in the AVAIL_SPECTRUM_BATCH_REQ message. 1233 geoSpectrumSpecs: The geoSpectrumSpecs (Section 5.15) list is 1234 REQUIRED (although it MAY be empty if spectrum is unavailable). 1235 For each location, the Database MAY return one or more 1236 SpectrumSpecs (Section 5.9) to represent available spectrum for 1237 one or more rulesets. The Database MAY return available spectrum 1238 for fewer locations than requested. The order of the entries in 1239 the list is not significant and the device MUST use the location 1240 value in each GeoSpectrumSpec entry to match available spectrum to 1241 a location. 1243 databaseChange: The Database MAY include a DbUpdateSpec 1244 (Section 5.7) to notify the device of a change to the Database 1245 URI, providing one or more alternate database URIs. The device 1246 needs to update its preconfigured entry for the responding 1247 database with the alternate databases listed in the DbUpdateSpec. 1249 other: Database implementations MAY return additional parameters in 1250 the response. Consult the PAWS Parameters Registry (Section 9.2) 1251 for possible additional parameters and requirements they place on 1252 the device. 1254 See Update Requirements (Section 4.5.2.1) for when the device must 1255 update its available spectrum data. 1257 4.5.5. SPECTRUM_USE_NOTIFY 1259 The spectrum-use notification message indicates the spectrum 1260 anticipated to be used by the device. 1262 +---------------------------------------------------+ 1263 |SPECTRUM_USE_NOTIFY | 1264 +---------------------------------+-----------------+ 1265 |deviceDesc:DeviceDescriptor | required | 1266 |location:GeoLocation | see description | 1267 |masterDeviceDesc:DeviceDescriptor| optional | 1268 |masterDeviceLocation:GeoLocation | see description | 1269 |spectra:list | required |--+ 1270 |...................................................| | 1271 |*other:any | optional | | 1272 +---------------------------------+-----------------+ | 0..* 1273 V 1274 +--------------------------------+ 1275 |Spectrum | 1276 +---------------------+----------+ 1277 |resolutionBwHz:float | required | 1278 |profiles:list | required | 1279 +---------------------+----------+ 1281 Parameters: 1283 deviceDesc: The DeviceDescriptor (Section 5.2) for the device is 1284 REQUIRED. 1286 location: The GeoLocation (Section 5.1) for the device. When the 1287 notification is made by a Master Device on its own behalf, the 1288 location is that of the Master Device and is REQUIRED. When the 1289 notification is made by a Master Device on behalf of a Slave 1290 Device, the location is that of the Slave Device and is OPTIONAL, 1291 but may be required by some rulesets. 1293 spectra: The Spectrum (Section 5.11) list is REQUIRED, and specifies 1294 the spectrum anticipated to be used by the device, which includes 1295 profiles of frequencies and power levels. The list MAY be empty, 1296 if the device decides not to use any spectrum. For consistency, 1297 the resolution bandwidth value, "resolutionBwHz" MUST match that 1298 from one of the Spectrum (Section 5.11) elements in the 1299 corresponding AVAIL_SPECTRUM_RESP message, and the maximum power 1300 levels in the Spectrum element MUST be expressed as power (EIRP) 1301 over the specified "resolutionBwHz" value. The actual bandwidth 1302 to be used (as computed from the start and stop frequencies) MAY 1303 be different from the "resolutionBwHz" value. As an example, when 1304 the ruleset expresses maximum power spectral density in terms of 1305 maximum power over any 100 kHz band, then the "resolutionBwHz" 1306 value should be set to 100 kHz, even though the actual bandwidth 1307 used can be 20 kHz. 1309 masterDeviceDesc: When the notification is made by the Master Device 1310 on behalf of a Slave Device, the Master Device MAY provide its own 1311 descriptor. 1313 masterDeviceLocation: When the notification is made by the Master 1314 Device on behalf of a Slave Device, the Master Device MUST include 1315 its own GeoLocation (Section 5.1). 1317 other: Depending on the ruleset, other parameters may be required. 1318 To simplify its logic, the device MAY include the union of all 1319 parameters required by all supported rulesets. The Database MUST 1320 ignore all parameters it does not understand. 1322 4.5.6. SPECTRUM_USE_RESP 1324 The spectrum-use response message simply acknowledges receipt of the 1325 notification. 1327 +---------------------------------------+ 1328 |SPECTRUM_USE_RESP | 1329 +----------------------------+----------+ 1330 |databaseChange:DbUpdateSpec | optional | 1331 |.......................................| 1332 |*other:any | optional | 1333 +----------------------------+----------+ 1335 Parameters: 1337 databaseChange: The Database MAY include a DbUpdateSpec 1338 (Section 5.7) to notify the device of a change to the Database 1339 URI, providing one or more alternate database URIs. The device 1340 needs to update its preconfigured entry for the responding 1341 database with the alternate databases listed in the DbUpdateSpec. 1343 other: Database implementations MAY return additional parameters in 1344 the response. Consult the PAWS Parameters Registry (Section 9.2) 1345 for possible additional parameters. 1347 4.6. Device Validation 1349 A Slave Device needs a Master Device to ask the Database on its 1350 behalf for available spectrum. Depending on the ruleset, the Master 1351 Device also must validate with the Database that the Slave Device is 1352 permitted to operate. When the ruleset allows a Master Device to 1353 "cache" the available spectrum for a period of time, the Master 1354 Device may use the simpler Device Validation component, instead of 1355 the full Available Spectrum Query component, to validate a Slave 1356 Device. 1358 When validating one or more Slave Devices, the Master Device sends 1359 the Database a request that includes the device identifier -- and any 1360 other parameters required by the ruleset -- for each Slave Device. 1361 The Database MUST return a response with an entry for each device to 1362 indicate whether it is permitted to use the spectrum. 1364 A typical sequence for using the Device Validation request is 1365 illustrated in Figure 5, where the Master Device already has a valid 1366 set of available spectrum for Slave Devices. Note that the 1367 communication and protocol between the Slave Device and Master Device 1368 is outside the scope of this document. 1370 o DEV_VALID_REQ (Section 4.6.1) is the device-validation request 1371 message 1373 o DEV_VALID_RESP (Section 4.6.2) is the device-validation response 1374 message 1375 +------------+ +---------------+ +-------------------+ 1376 |Slave Device| | Master Device | | Spectrum Database | 1377 +------------+ +---------------+ +-------------------+ 1378 | | | 1379 | AVAIL_SPEC_REQ | | 1380 |................>| | 1381 | | | 1382 | | DEV_VALID_REQ | 1383 | |-------------------------->| 1384 | | | 1385 | | DEV_VALID_RESP | 1386 | |<--------------------------| 1387 | AVAIL_SPEC_RESP | | 1388 |<................| | 1389 | | | 1390 | (SPECTRUM_USE) | | 1391 |................>| (SPECTRUM_USE_NOTIFY) | 1392 | |-------------------------->| 1393 | | | 1394 | | (SPECTRUM_USE_RESP) | 1395 | |<--------------------------| 1397 Figure 5 1399 4.6.1. DEV_VALID_REQ 1401 This request is used by a Master Device to determine which Slave 1402 Devices are permitted to operate. 1404 +---------------------------------------------+ 1405 |DEV_VALID_REQ | 1406 +----------------------------------+----------+ 1407 |deviceDescs:list | required |---+ 1408 |masterDeviceDesc:DeviceDescriptor | optional | | 1409 +----------------------------------+----------+ | 1410 V 1..* 1411 +----------------------+ 1412 |DeviceDescriptor | 1413 +----------------------+ 1415 Parameters: 1417 deviceDescs: A DeviceDescriptor (Section 5.2) list is REQUIRED, 1418 which specifies the list of Slave Devices that are to be 1419 validated. 1421 masterDeviceDesc: The Master Device MAY provide its own descriptor. 1423 4.6.2. DEV_VALID_RESP 1425 +---------------------------------------+ 1426 |DEV_VALID_RESP | 1427 +----------------------------+----------+ 1428 |deviceValidities:list | required |---- 1429 |databaseChange:DbUpdateSpec | optional | | 1430 +----------------------------+----------+ | 1431 V 1..* 1432 +---------------------------------------+ 1433 |DeviceValidity | 1434 +----------------------------+----------+ 1435 |deviceDesc:DeviceDescriptor | required | 1436 |isValid:boolean | required | 1437 |reason:string | optional | 1438 +----------------------------+----------+ 1440 Parameters: 1442 deviceValidities: A DeviceValidities (Section 5.16) list is REQUIRED 1443 to report the list of Slave Devices and whether each listed device 1444 is valid. The number of entries MUST match the number of 1445 DeviceDescriptors (Section 5.2) listed in the DEV_VALID_REQ 1446 message. 1448 databaseChange: The Database MAY include a DbUpdateSpec 1449 (Section 5.7) to notify the device of a change to the Database 1450 URI, providing one or more alternate database URIs. The device 1451 needs to update its preconfigured entry for the responding 1452 database with the alternate databases listed in the DbUpdateSpec. 1454 5. Protocol Parameters 1456 This section presents more details of the parameters that make up the 1457 PAWS request and response messages. It also includes a sub-section 1458 defining response codes. 1460 5.1. GeoLocation 1462 GeoLocation is used to specify one of the following: 1464 o A single point with optional uncertainty 1466 o A region described by a polygon 1468 These are represented using geometric shapes defined in Section 5 of 1469 "GEOPRIV Presence Information Data Format Location Object" [RFC5491], 1470 where: 1472 o A "point" with uncertainty is represented using the Ellipse shape 1474 o A region is represented using the Polygon shape 1476 The coordinates are expressed using the WGS84 datum [WGS-84], and 1477 units are degrees or meters. GeoLocation MAY also include a 1478 confidence level, expressed as a percentage. The confidence and 1479 uncertainty parameters may be required by some rulesets (see also 1480 Uncertainty and Confidence [I-D.ietf-geopriv-uncertainty]). 1482 The data model for GeoLocation is illustrated below: 1484 +------------------------------------+ 1485 |GeoLocation | 1486 +------------------+-----------------+ 1487 |point:Ellipse | see description | 1488 |region:Polygon | see description | 1489 |confidence:int | optional | 1490 +------------------+-----------------+ 1491 Note: point and region are mutually exclusive. Exactly one must 1492 be present. 1494 +-------------------------------+ 1495 |Ellipse | 1496 +--------------------+----------+ 1497 |center:Point | required |--+ 1498 |semiMajorAxis:float | optional | | 1499 |semiMinorAxis:float | optional | | 1500 |orientation:float | optional | | 1501 +--------------------+----------+ v 1502 +---------------------------+ 1503 |Point | 1504 +----------------+----------+ 1505 |latitude:float | required | 1506 |longitude:float | required | 1507 +----------------+----------+ 1509 +-------------------------------+ 1510 |Polygon | 1511 +-------------------+-----------+ 4..* +---------------------------+ 1512 |exterior:list | required |------>|Point | 1513 +-------------------+-----------+ +----------------+----------+ 1514 |latitude:float | required | 1515 |longitude:float | required | 1516 +----------------+----------+ 1518 Parameters: 1520 point: If present, it specifies the GeoLocation as a point. 1521 Paradoxically, a "point" is parameterized using an Ellipse, where 1522 the center represents the location of the point and the distances 1523 along the major and minor axes represent the uncertainty. The 1524 uncertainty values may be required, depending on the ruleset. 1525 Exactly one of "point" or "region" MUST be present. 1527 region: If present, it specifies the GeoLocation as a region. 1528 Exactly one of "point" or "region" MUST be present. 1530 center: The center refers to the location of a GeoLocation point and 1531 is represented as the center of an ellipse. 1533 latitude, longitude: Floating-point numbers that express the 1534 latitude and longitude in degrees using the WGS84 datum [WGS-84]. 1536 semiMajorAxis, semiMinorAxis: This OPTIONAL parameter expresses the 1537 location uncertainty, expressed in meters. It is parameterized 1538 using distances along the major and minor axes of the ellipse. 1539 The default value for each parameter is 0. 1541 orientation: This defines the orientation of the ellipse, expressed 1542 as the rotation, in degrees, of the semi-major axis from North 1543 towards the East. For example, when the uncertainty is greatest 1544 along the North-South direction, orientation is 0 degrees; 1545 conversely, if the uncertainty is greatest along the East-West 1546 direction, orientation is 90 degrees. When orientation is not 1547 present, the default value is 0. 1549 exterior: When GeoLocation describes a region, the "exterior" 1550 parameter refers to a list of latitude/longitude points that 1551 represents the vertices of a polygon. The first and last points 1552 MUST be the same. Thus, a minimum of 4 points is required. The 1553 following polygon restrictions from [RFC5491] apply: 1555 * A connecting line MUST NOT cross another connecting line of the 1556 same polygon. 1558 * The vertices MUST be defined in a counter-clockwise direction, 1559 looking at them from above. 1561 * The edges of a polygon are defined by the shortest path between 1562 two points in space (not a geodesic curve). Consequently, the 1563 length between two adjacent vertices SHOULD be restricted to a 1564 maximum of 130 km. 1566 * All vertices are assumed to be at the same altitude. 1568 * Polygon shapes SHOULD be restricted to a maximum of 15 vertices 1569 (16 points that includes the repeated vertex). 1571 confidence: The location confidence level, as a percentage, MAY be 1572 provided. When this parameter is not provided, the default value 1573 is 95. Valid values range from 0 to 100, but, in practice, 1574 100-percent confidence is not achievable. The confidence value is 1575 meaningful only when GeoLocation refers to a point with 1576 uncertainty. 1578 5.2. DeviceDescriptor 1580 The device descriptor contains parameters that identify the specific 1581 device, such as its manufacturer serial number, manufacturer's ID, 1582 and any other device characteristics required by ruleset. 1584 +--------------------------------+ 1585 |DeviceDescriptor | 1586 +---------------------+----------+ 1587 |serialNumber:string | optional | 1588 |manufacturerId:string| optional | 1589 |modelId:string | optional | 1..* 1590 |rulesetIds:list | optional |------>string 1591 |.....................|..........| 1592 |*other:any | optional | 1593 +---------------------+----------+ 1595 Parameters: 1597 serialNumber: The manufacturer's device serial number is OPTIONAL, 1598 although rulesets typically require it. Its maximum length is 64 1599 octets. 1601 manufacturerId: The manufacturer's ID is OPTIONAL, but may be 1602 required by some rulesets. This represents the name of the device 1603 manufacturer, and therefore ought to be consistent across all 1604 devices from the same manufacturer and distinct from that of other 1605 manufacturers. Its maximum length is 64 octets. 1607 modelId: The device's model ID is OPTIONAL, but may be required by 1608 some rulesets. Its maximum length is 64 octets. 1610 rulesetIds: The list of identifiers for rulesets supported by the 1611 device (see Ruleset ID Registry (Section 9.1)). A Database MAY 1612 require that the device provides this list before servicing the 1613 device requests. If the Database supports none of the rulesets 1614 specified in the list, the Database MAY refuse to service the 1615 device requests. See RulesetInfo (Section 5.6) for discussion on 1616 ruleset identifier. If present, the list MUST contain at least 1617 one entry. 1619 other: Depending on the ruleset, other parameters may be required. 1620 The Database MUST ignore all parameters in the message it does not 1621 understand. See PAWS Parameters Registry (Section 9.2) for 1622 additional valid parameters and for the process for extending the 1623 message with more parameters. Additionally, see PAWS Ruleset ID 1624 Registry (Section 9.1) for the valid set of parameters for each 1625 ruleset. 1627 5.3. AntennaCharacteristics 1629 Antenna characteristics provide additional information, such as the 1630 antenna height, antenna type, etc. Whether antenna characteristics 1631 must be provided in a request depends on the device type and ruleset. 1632 Additionally, a parameter marked as optional may be required by some 1633 rulesets. 1635 +------------------------------------+ 1636 |AntennaCharacteristics | 1637 +-------------------------+----------+ 1638 |height:float | optional | 1639 |heightType:enum | optional | 1640 |heightUncertainty:float | optional | 1641 |.........................|..........| 1642 |*characteristics: | optional | 1643 | various | | 1644 +-------------------------+----------+ 1646 Parameters: 1648 height: The antenna height in meters. Note that the height may be 1649 negative. 1651 heightType: Valid values are: 1653 AGL Above ground level (default) 1655 AMSL Above mean sea level 1657 heightUncertainty: The height uncertainty in meters. 1659 NOTE: Depending on the ruleset, additional antenna characteristics 1660 may be required, such as: 1662 o antenna direction 1663 o antenna radiation pattern 1665 o antenna gain 1667 o antenna polarization 1669 These are not defined by the base protocol, but may be added to the 1670 PAWS Parameters Registry (Section 9.2), as needed. 1672 5.4. DeviceCapabilities 1674 Device capabilities provide additional information that may be used 1675 by the device to provide additional information to the Database that 1676 can help it to determine available spectrum. If the Database does 1677 not support device capabilities it MUST ignore the parameter 1678 altogether. 1680 +-------------------------------+ 1681 |DeviceCapabilities | 1682 +---------------------+---------+ 1683 |frequencyRanges:list |optional |--+ 1684 |.....................|.........| | 1685 |*other:any |optional | | 1686 +---------------------+---------+ | 0..* 1687 V 1688 +--------------------------------+ 1689 |FrequencyRange | 1690 +----------------------+---------+ 1691 |startHz:float |required | 1692 |stopHz:float |required | 1693 +----------------------+---------+ 1695 Parameters: 1697 frequencyRanges: Optional FrequencyRange (Section 5.13) list. Each 1698 FrequencyRange element contains start and stop frequencies in 1699 which the device can operate. When specified, the Database SHOULD 1700 NOT return available spectrum that falls outside these ranges. 1702 other Consult the PAWS Parameters Registry (Section 9.2) for 1703 possible additional parameters. The Database MUST ignore all 1704 parameters it does not understand. 1706 5.5. DeviceOwner 1708 DeviceOwner contains information on device ownership that is provided 1709 as part of device registration. Some rulesets may require additional 1710 parameters. 1712 +-----------------------------+ 1713 |DeviceOwner | 1714 +------------------+----------+ 1715 |owner:vcard | required | 1716 |operator:vcard | optional | 1717 +------------------+----------+ 1719 Parameters: 1721 owner: The vCard contact information for the individual or business 1722 that owns the device is REQUIRED. 1724 operator: The vCard contact information for the device operator is 1725 OPTIONAL, but may be required by specific rulesets. 1727 See PAWS Ruleset ID Registry (Section 9.1) for ruleset-specific 1728 requirements on mandatory vCard properties. Depending on the 1729 ruleset, the Database may be required to validate the device-owner 1730 information. In these cases, the Database MUST respond with an 1731 INVALID_VALUE error (see Error Codes (Section 5.17)) if validation 1732 fails. 1734 All contact information MUST be expressed using the structure defined 1735 by the "vCard Format Specification" [RFC6350], encoded in JSON 1736 [RFC7095]. Note that the vCard specification defines maximum lengths 1737 for each parameter. 1739 5.6. RulesetInfo 1741 RulesetInfo contains parameters for the ruleset of a regulatory 1742 domain that is communicated using the Initialization component 1743 (Section 4.3), Device Registration (Section 4.4), and Available 1744 Spectrum Query (Section 4.5) components. 1746 +------------------------------------------+ 1747 |RulesetInfo | 1748 +------------------------------------------+ 1749 |authority:string | required | 1750 |rulesetId:string | required | 1751 |maxLocationChange:float | see description | 1752 |maxPollingSecs:int | see description | 1753 |..........................................| 1754 |*other:any | optional | 1755 +------------------------+-----------------+ 1757 Parameters: 1759 authority: A string that indicates the regulatory domain to which 1760 the ruleset applies is REQUIRED. It will normally be a 2-letter 1761 country code defined by Country Codes - ISO 3166 [ISO3166-1]. 1763 rulesetId: The ID of a ruleset for the specified authority (see 1764 Ruleset ID Registry (Section 9.1)). The device can use this to 1765 determine additional device behavior required by the associated 1766 ruleset. To define new ruleset IDs, see Defining Ruleset 1767 Identifiers (Section 8.1). 1769 maxLocationChange: The maximum location change in meters is REQUIRED 1770 for Initialization Response (Section 4.3.2), but OPTIONAL 1771 otherwise. Some regulatory domains mandate that, when the device 1772 changes location by more than this specified distance, it contact 1773 the Database to get the available spectrum for the new location. 1774 If this value is provided by the Database within the context of an 1775 Available Spectrum Response (Section 4.5.2), it takes precedence 1776 over the value within the Initialization Response (Section 4.3.2). 1778 maxPollingSecs: The maximum duration, in seconds, between requests 1779 for available spectrum is REQUIRED for the Initialization Response 1780 (Section 4.3.2), but OPTIONAL otherwise. The device MUST contact 1781 the Database to get available spectrum no less frequently than 1782 this duration. If this value is provided within the context of an 1783 Available Spectrum Response (Section 4.5.2), it takes precedence 1784 over the value within the Initialization Response (Section 4.3.2). 1786 other: Depending on the ruleset, other parameters may be required. 1787 Devices MUST ignore all parameters in the message it does not 1788 understand. Consult the PAWS Parameters Registry (Section 9.2) 1789 for possible additional parameters. 1791 5.7. DbUpdateSpec 1793 This element is provided by the Database to notify devices of an 1794 upcoming change to the Database URI. 1796 +-------------------------------+ 1797 |DbUpdateSpec | 1798 +---------------------+---------+ +--------------------------+ 1799 |databases:list |required |------>|DatabaseSpec | 1800 +---------------------+---------+ 1..* +---------------+----------+ 1801 |name:string | required | 1802 |uri:string | required | 1803 +---------------+----------+ 1805 Parameters: 1807 databases: List of one or more DatabaseSpec (Section 5.8) entries. 1808 A device needs to update its preconfigured entry for the 1809 responding database with the alternate databases listed in the 1810 DbUpdateSpec. 1812 5.8. DatabaseSpec 1814 This element contains the name and URI of a database. 1816 +--------------------------+ 1817 |DatabaseSpec | 1818 +---------------+----------+ 1819 |name:string | required | 1820 |uri:string | required | 1821 +---------------+----------+ 1823 Parameters: 1825 name: The display name. Its maximum length is 64 octets. 1827 uri: The corresponding URI of the database. Its maximum length is 1828 1024 octets. 1830 5.9. SpectrumSpec 1832 The SpectrumSpec element encapsulates the schedule of available 1833 spectrum for a ruleset. 1835 +---------------------------------------+ 1836 |SpectrumSpec | 1837 +----------------------------+----------+ 1838 |rulesetInfo:RulesetInfo | required | 1839 |spectrumSchedules:list | required |-----+ 1840 |timeRange:EventTime | optional | | 1841 |frequencyRanges:list | optional | | 1842 |needsSpectrumReport:boolean | optional | | 1843 |maxTotalBwHz:float | optional | | 1844 |maxContiguousBwHz:float | optional | | 1845 +----------------------------+----------+ | 1846 | 1..* 1847 V 1848 +-------------------------------+ 1849 |SpectrumSchedule | 1850 +--------------------+----------+ 1851 |eventTime:EventTime | required | 1852 |spectra:list | required | 1853 +--------------------+----------+ 1855 Parameters: 1857 rulesetInfo: RulesetInfo (Section 5.6) is REQUIRED to identify the 1858 regulatory domain and ruleset to which the spectrum schedule 1859 applies (see Ruleset ID Registry (Section 9.1)). The device needs 1860 to use the corresponding ruleset to interpret the response. 1861 Values provided within rulesetInfo, such as maxLocationChange, 1862 take precedence over the values provided by the Initialization 1863 Procedure (Section 4.3). 1865 spectrumSchedules: The SpectrumSchedule (Section 5.10) list is 1866 REQUIRED. At least one schedule MUST be included. More than one 1867 schedule MAY be included to represent future changes to the 1868 available spectrum. How far in advance a schedule may be provided 1869 depends on the ruleset. If more than one schedule is included, 1870 the eventTime intervals MUST be disjoint and MUST be sorted in 1871 increasing time. A gap in the time schedule indicates no 1872 available spectrum during that time-interval gap. 1874 timeRange: The time range for which the specification is 1875 comprehensive is OPTIONAL. When specified, any gaps in time 1876 intervals within the "spectrumSchedules" element that overlaps 1877 with the range specified by "timeRange" are interpreted by the 1878 device as time intervals in which there is no available spectrum. 1880 frequencyRanges: The frequency ranges for which the specification is 1881 comprehensive is OPTIONAL. It is a list of disjoint 1882 FrequencyRange (Section 5.13) entries. When specified, it 1883 typically corresponds to the frequency ranges governed by the 1884 ruleset, e.g., for TV whitespace, the frequency ranges can 1885 correspond to the VHF and UHF bands of the associated regulatory 1886 domain. A device can combine this information with the available- 1887 spectrum specification within the "spectrumSchedules" element to 1888 distinguish between "unavailable spectrum" and "spectrum for which 1889 no information has been provided". 1891 needsSpectrumReport: The Database MAY return true for this parameter 1892 if spectrumSchedules list is non-empty; otherwise, the Database 1893 MAY omit this parameter altogether, in which case, the default 1894 value is false. If this parameter is present and its value is 1895 true, the device sends a SPECTRUM_USE_NOTIFY (Section 4.5.5) 1896 message to the Database; otherwise, the device SHOULD NOT send the 1897 SPECTRUM_USE_NOTIFY message. Some rulesets mandate this value to 1898 be true. 1900 maxTotalBwHz: The Database MAY return a constraint on the maximum 1901 total bandwidth (in Hertz) allowed, which may or may not be 1902 contiguous. Some rulesets mandate the Database to return this 1903 parameter. When present in the response, the device needs to 1904 apply this constraint to its spectrum-selection logic to ensure 1905 total bandwidth does not exceed this value. 1907 maxContiguousBwHz: The Database MAY return a constraint on the 1908 maximum contiguous bandwidth (in Hertz) allowed. Some rulesets 1909 mandate the Database to return this parameter. When present in 1910 the response, the device needs to apply this constraint to its 1911 spectrum-selection logic to ensure no single block of spectrum has 1912 bandwidth that exceeds this value. 1914 5.10. SpectrumSchedule 1916 The SpectrumSchedule element combines EventTime (Section 5.14) with 1917 Spectrum (Section 5.11) to define a time period in which the spectrum 1918 is valid. 1920 +-------------------------------+ 1921 |SpectrumSchedule | 1922 +--------------------+----------+ 1923 |eventTime:EventTime | required | +--------------------+ 1924 |spectra:list | required |------->|Spectrum | 1925 +--------------------+----------+ 0..* +--------------------+ 1926 |resolutionBwHz:float| 1927 |profiles:list | 1928 +--------------------+ 1930 Parameters: 1932 eventTime: The EventTime (Section 5.14) is REQUIRED to express 1933 "when" this specification is valid. 1935 spectra: The Spectrum (Section 5.11) list is REQUIRED to specify the 1936 available spectrum and permissible power levels, one per 1937 resolutionBwHz. The list MAY be empty when there is no available 1938 spectrum. 1940 5.11. Spectrum 1942 Available spectrum can be characterized by an ordered list of 1943 spectrum profiles that defines permissible power levels over a set of 1944 frequency ranges. Each Spectrum element defines permissible power 1945 levels as maximum power spectral densities over a specified 1946 resolution bandwidth, "resolutionBwHz". Note that the spectrum 1947 profiles represent the "availability mask", as defined by the 1948 governing rule set; they are not intended to encode device-level 1949 transmission-mask requirements. 1951 NOTE: Within the contexts of the AVAIL_SPECTRUM_RESP (Section 4.5.2), 1952 AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4), and SPECTRUM_USE_NOTIFY 1953 (Section 4.5.5) messages, the power levels expressed within the 1954 Spectrum messages refer to EIRP. Future extensions of PAWS may use 1955 Spectrum in other contexts for other definitions of power levels. 1957 o To support a ruleset that defines different "wide-band" and 1958 "narrow-band" power levels, PAWS allows multiple Spectrum elements 1959 to be included in the available-spectrum response, each with a 1960 different resolution bandwidth. 1962 o When multiple Spectrum elements are included in the response, each 1963 represents a constraint that the device must satisfy (logical 1964 AND). 1966 o Each Spectrum element covers the range of frequencies governed by 1967 a ruleset, rather than splitting the frequencies across multiple 1968 Spectrum elements for the same resolution bandwidth. 1970 o Each spectrum profile represents the maximum permissible power 1971 spectral density over a contiguous range of frequencies. 1973 o When multiple spectrum profiles are included, they MUST be 1974 disjoint and MUST be ordered in non-decreasing frequency value. 1976 o Gaps in frequencies between consecutive spectrum profiles 1977 represent unavailability for those frequencies. 1979 The following figure illustrates the Spectrum element and the 1980 SpectrumProfile list. 1982 +-------------------------------+ 1983 |Spectrum | 1984 +---------------------+---------+ 1985 |resolutionBwHz:float |required | 1986 |profiles:list |required |---+ 1987 +---------------------+---------+ | 0..* 1988 V 1989 +-----------------------------+ 1990 |SpectrumProfile | 1991 +-------------------+---------+ 1992 |list |required | 1993 +-------------------+---------+ 1994 | 1995 V 2..* 1996 +--------------------------+ 1997 |SpectrumProfilePoint | 1998 +----------------+---------+ 1999 |hz:float |required | 2000 |dbm:float |required | 2001 +----------------+---------+ 2003 Parameters: 2005 resolutionBwHz: This parameter defines the resolution bandwidth (in 2006 Hertz) over which permissible power spectral density is defined. 2007 For example, FCC regulation would require one spectrum 2008 specification at a bandwidth of 6MHz, and ETSI regulation would 2009 require two specifications, at 0.1MHz and 8MHz. 2011 profiles: A SpectrumProfile (Section 5.12) list specifies 2012 permissible power levels over a set of frequency ranges. The list 2013 MAY be empty if there is no available spectrum. 2015 The following example shows permitted power spectral densities for a 2016 single resolution bandwidth of 6MHz (for illustrative purposes only): 2018 [ 2019 { 2020 "resolutionBwHz": 6e6, 2021 "profiles": [ 2022 [ 2023 {"hz": 5.18e8, "dbm": 30.0}, 2024 {"hz": 5.30e8, "dbm": 30.0} 2025 ], 2026 ... 2027 ] 2028 } 2029 ] 2030 This is interpreted as: 2032 o Over any 6MHz within the frequency range, [518MHz, 530MHz), 2033 maximum permitted power is 30.0dBm (1000mW) 2035 Consider now an example with two different sets of permitted power 2036 spectral densities for the same set of frequencies over different 2037 resolution bandwidths (for illustrative purposes only): 2039 [ 2040 { 2041 "resolutionBwHz": 6e6, 2042 "profiles": [ 2043 [ 2044 {"hz": 5.18e8, "dbm": 30.0}, 2045 {"hz": 5.30e8, "dbm": 30.0} 2046 ], 2047 ... 2048 ] 2049 }, 2050 { 2051 "resolutionBwHz": 1e5, 2052 "profiles": [ 2053 [ 2054 {"hz": 5.18e8, "dbm": 27.0}, 2055 {"hz": 5.30e8, "dbm": 27.0} 2056 ], 2057 ... 2058 ] 2059 } 2060 ] 2062 This is interpreted as: 2064 o Over any 6MHz within the frequency range, [518MHz, 530MHz), 2065 maximum permitted power is 30.0dBm (1000mW), and 2067 o Over any 100 kHz within the frequency range, [518MHz, 530MHz), 2068 maximum permitted power is 27.0dBm (500mW) 2070 This would allow, for example, operating two 100kHz sub-channels 2071 within the indicated 12MHz range at 500mW each, totaling 1000mW. Of 2072 course, many combinations are possible, as long as they satisfy both 2073 conditions. 2075 The following example encodes multiple (two) spectrum profiles, each 2076 having a gap from 530 MHz to 536 MHz (for illustrative purposes 2077 only): 2079 [ 2080 { 2081 "resolutionBwHz": 6e6, 2082 "profiles": [ 2083 [ 2084 {"hz": 5.18e8, "dbm": 30.0}, 2085 {"hz": 5.24e8, "dbm": 30.0}, 2086 {"hz": 5.24e8, "dbm": 36.0}, 2087 {"hz": 5.30e8, "dbm": 36.0} 2088 ], 2089 [ 2090 {"hz": 5.36e8, "dbm": 30.0}, 2091 {"hz": 5.42e8, "dbm": 30.0} 2092 ], 2093 ... 2094 ] 2095 }, 2096 { 2097 "resolutionBwHz": 1e5, 2098 "profiles": [ 2099 [ 2100 {"hz": 5.18e8, "dbm": 27.0}, 2101 {"hz": 5.24e8, "dbm": 27.0}, 2102 {"hz": 5.24e8, "dbm": 30.0}, 2103 {"hz": 5.30e8, "dbm": 30.0} 2104 ], 2105 [ 2106 {"hz": 5.36e8, "dbm": 27.0}, 2107 {"hz": 5.42e8, "dbm": 27.0} 2108 ], 2109 ... 2110 ] 2111 } 2112 ] 2114 5.12. SpectrumProfile 2116 A spectrum profile is characterized by an ordered list of (frequency, 2117 power) points that represents the shape of maximum permissible power 2118 levels over a range of frequencies as a piecewise linear curve. 2120 o It MUST contain a minimum of two entries. 2122 o The entries in the list MUST be ordered in non-decreasing 2123 frequency values. 2125 o Two consecutive points MAY have the same frequency value to 2126 represent a "step function". 2128 o Three or more points MUST NOT share the same frequency value. 2130 o The first frequency is inclusive; the last frequency is exclusive. 2132 NOTE: This encoding allows presentation of "ramps" where the slope of 2133 a line segment may be finite and non-zero. 2135 The following figure illustrates the SpectrumProfile element. 2137 +-------------------------------+ 2138 |SpectrumProfile | 2139 +---------------------+---------+ 2140 |list |required |---+ 2141 +---------------------+---------+ | 2..* 2142 V 2143 +--------------------------+ 2144 |SpectrumProfilePoint | 2145 +----------------+---------+ 2146 |hz:float |required | 2147 |dbm:float |required | 2148 +----------------+---------+ 2150 Parameters of each point in the profile: 2152 hz: The frequency, in Hertz, at which the power level is defined. 2154 dbm: The power level, expressed as dBm per resolution bandwidth, as 2155 defined by the "resolutionBwHz" element of the enclosing Spectrum 2156 (Section 5.11) element. 2158 5.13. FrequencyRange 2160 FrequencyRange specifies a frequency range. 2162 +--------------------------------+ 2163 |FrequencyRange | 2164 +----------------------+---------+ 2165 |startHz:float |required | 2166 |stopHz:float |required | 2167 +----------------------+---------+ 2169 Parameters: 2171 startHz: The inclusive start of the frequency range (in Hertz) is 2172 REQUIRED. 2174 stopHz: The exclusive end of the frequency range (in Hertz) is 2175 REQUIRED. 2177 5.14. EventTime 2179 The EventTime element specifies the start and stop times of an 2180 "event". This is used to indicate the time period for which a 2181 Spectrum (Section 5.11) is valid. 2183 +---------------------------+ 2184 |EventTime | 2185 +-----------------+---------+ 2186 |startTime:string |required | 2187 |stopTime:string |required | 2188 +-----------------+---------+ 2190 Parameters: 2192 startTime: The inclusive start of the event is REQUIRED. 2194 stopTime: The exclusive end of the event is REQUIRED. 2196 Both times are expressed using the format, YYYY-MM-DDThh:mm:ssZ, as 2197 defined by "Date and Time on the Internet: Timestamps" [RFC3339]. 2198 The times MUST be expressed using UTC. 2200 A device that does not have access to the current date and time MUST 2201 use the timestamp at the top-level of the response message as a 2202 substitute for the current time (see Available Spectrum Response 2203 (Section 4.5.2) and Available Spectrum Batch Response 2204 (Section 4.5.4)). E.g., 2206 o (startTime - timestamp) gives the duration that a device must wait 2207 before the event becomes "active". If the value is zero or 2208 negative, the event is already active. 2210 o If the event is already active, (stopTime - timestamp) is the 2211 duration that the event remains active. If the value is zero or 2212 negative, the event is no longer active and MUST be ignored. 2214 5.15. GeoSpectrumSpec 2216 The GeoSpectrumSpec element encapsulates the available spectrum for a 2217 location. It is returned within a AVAIL_SPECTRUM_BATCH_RESP 2218 (Section 4.5.4) batch response that contains multiple GeoSpectrumSpec 2219 entries, each matching a location provided in the batch request. 2221 +----------------------------------+ 2222 |GeoSpectrumSpec | 2223 +-----------------------+----------+ 2224 |location:GeoLocation | required | 2225 |spectrumSpecs:list | required |-------+ 2226 +-----------------------+----------+ | 2227 | 1..* 2228 V 2229 +--------------+ 2230 | SpectrumSpec | 2231 +--------------+ 2233 Parameters: 2235 location: The GeoLocation (Section 5.1) identifies the location at 2236 which the spectrum schedule applies. 2238 spectrumSpecs: The SpectrumSpec (Section 5.9) list is REQUIRED. At 2239 least one entry MUST be included. Each entry represents schedules 2240 of available spectrum for a ruleset. More than one entry MAY be 2241 included to support multiple rulesets at a location. 2243 5.16. DeviceValidity 2245 The DeviceValidity element is used to indicate whether a device is 2246 valid. See Section 4.6.2. 2248 +---------------------------------------+ 2249 |DeviceValidity | 2250 +----------------------------+----------+ 2251 |deviceDesc:DeviceDescriptor | required | 2252 |isValid:boolean | required | 2253 |reason:string | optional | 2254 +----------------------------+----------+ 2256 Parameters: 2258 deviceDesc: The DeviceDescriptor (Section 5.2) that was used to 2259 check for validity is REQUIRED. 2261 isValid: This is a REQUIRED boolean value that indicates whether the 2262 device is valid. 2264 reason: If the device identifier is not valid, the Database MAY 2265 include a reason. The reason MAY be in any language. Its maximum 2266 length is 128 octets. 2268 5.17. Error Element 2270 If the Database responds to a PAWS request message with an error, it 2271 MUST include an Error element. 2273 +----------------------------------+ 2274 |Error | 2275 +----------------+-----------------+ 2276 |code:int | required | 2277 |message:string | optional | 2278 |data:any | see description | 2279 +----------------+-----------------+ 2281 Parameters: 2283 code: An integer code that indicates the error type is REQUIRED. 2284 Values MUST be within the range, -32768 to 32767, inclusive. 2286 message: A description of the error is OPTIONAL. It MAY be in any 2287 language. Its maximum length is 128 octets. 2289 data: The Database MAY include additional data. For some errors, 2290 additional data may be required (see Table 1). The device MUST 2291 ignore any data parameters it does not understand. 2293 The following table lists predefined and reserved error codes. They 2294 are loosely grouped into the following categories: 2296 -100s: Indicates compatibility issues, e.g., version mismatch, 2297 unsupported or unimplemented features. 2299 -200s: Indicates that the device request contains an error that 2300 needs to be modified before making another request. 2302 -300s: Indicates authorization-related issues. 2304 Values that are not defined explicitly in the Error Codes 2305 Table (Table 1) below are unassigned. To define new error codes, see 2306 PAWS Error Code Registry (Section 9.3). 2308 Code Name Description & Additional parameters 2309 ------ ---------------- --------------------------------------------- 2310 0 (reserved) 2311 -100 (reserved) 2312 -101 VERSION The Database does not support the specified 2313 version of the message. This error does not 2314 use any additional data. 2315 -102 UNSUPPORTED The Database does not support the device. For 2316 example, it supports none of the ruleset 2317 specified in the request or does not support 2318 the device, based on its device type, model, 2319 etc. This error does not use any additional 2320 data. 2321 -103 UNIMPLEMENTED The Database does not implement the optional 2322 request or optional feature. This error does 2323 not use any additional data. 2324 -104 OUTSIDE_COVERAGE The specified geolocation is outside the 2325 coverage area of the Database. The Database 2326 MAY include a DbUpdateSpec (Section 5.7) to 2327 provide a list of alternate databases that 2328 might be appropriate for the requested 2329 location. See OUTSIDE_COVERAGE Error (Section 2330 5.17.1) for more details. 2331 -105 DATABASE_CHANGE The Database has changed its URI. The 2332 Database MAY include a DbUpdateSpec (Section 2333 5.7) in the error response to provide devices 2334 with one or more alternate database URIs. The 2335 device needs to update its preconfigured 2336 entry for the responding database with the 2337 alternate databases listed in the 2338 DbUpdateSpec. See DATABASE_CHANGE Error 2339 (Section 5.17.2) for more details. 2340 -200 (reserved) 2341 -201 MISSING A required parameter is missing. The Database 2342 MUST include a list of the required parameter 2343 names. The Database MAY include only names of 2344 parameters that are missing, but MAY include 2345 a full list. Including the full list of 2346 missing parameters may reduce the number of 2347 re-queries from the device. See MISSING Error 2348 (Section 5.17.3) for more details. 2349 -202 INVALID_VALUE A parameter value is invalid in some way. The 2350 Database SHOULD include a message indicating 2351 which parameter and why its value is invalid. 2352 This error does not use any additional data. 2353 -300 (reserved) 2354 -301 UNAUTHORIZED The device is not authorized to used the 2355 Database. Authorization may be determined by 2356 the ruleset or be dependent on prior 2357 arrangement between the device and Database. 2358 This error does not use any additional data. 2359 -302 NOT_REGISTERED Device registration required, but the device 2360 is not registered. This error does not use 2361 any additional data. 2362 -32000 (reserved) Reserved for JSON-RPC error codes. 2363 to 2364 -32768 2366 Table 1: Error Codes 2368 5.17.1. OUTSIDE_COVERAGE Error 2370 When the error code is OUTSIDE_COVERAGE, the Database MAY include an 2371 ErrorData element within its Error response as the "data" parameter, 2372 and, if present, the ErrorData contains a DbUpdateSpec (Section 5.7) 2373 element that provides a list of alternate databases that might be 2374 appropriate for the requested location. 2376 +---------------------------+ 2377 |Error | 2378 +----------------+----------+ 2379 |code:int | required | 2380 |message:string | optional | +-----------------------------+ 2381 |data:ErrorData | optional |--->|ErrorData | 2382 +----------------+----------+ +------------------+----------+ 2383 |spec:DbUpdateSpec | optional | 2384 +------------------+----------+ 2386 5.17.2. DATABASE_CHANGE Error 2388 When the error code is DATABASE_CHANGE, the Database MAY include an 2389 ErrorData element within its Error response as the "data" parameter, 2390 and, if present, the ErrorData contains a DbUpdateSpec (Section 5.7) 2391 element that provides a list of alternate databases. 2393 +---------------------------+ 2394 |Error | 2395 +----------------+----------+ 2396 |code:int | required | 2397 |message:string | optional | +-----------------------------+ 2398 |data:ErrorData | optional |--->|ErrorData | 2399 +----------------+----------+ +------------------+----------+ 2400 |spec:DbUpdateSpec | required | 2401 +------------------+----------+ 2403 5.17.3. MISSING Error 2405 When the error code is MISSING, the Database MUST include an 2406 ErrorData element within its Error response as the "data" parameter, 2407 and the ErrorData element MUST include a list of the missing required 2408 parameters and MAY include the list of all required parameters. 2410 +---------------------------+ 2411 |Error | 2412 +----------------+----------+ 2413 |code:int | required | 2414 |message:string | optional | +---------------------------+ 2415 |data:ErrorData | required |--->|ErrorData | 2416 +----------------+----------+ +----------------+----------+ 1..* 2417 |parameters:list | required |--+ 2418 +----------------+----------+ | 2419 v 2420 string 2422 Parameters: 2424 parameters: List of one or more parameter names (strings). The name 2425 of a parameter is expressed using dotted notation, when 2426 appropriate, e.g., "deviceDesc.serialNumber". 2428 6. Message Encoding 2430 PAWS is encoded using JSON-RPC [JSON-RPC] (see also "The JavaScript 2431 Object Notation (JSON) Data Interchange Format" [RFC7159]). Each 2432 component described in Protocol Functionalities (Section 4) 2433 corresponds to one or more JSON-RPC methods. This section discusses 2434 how to encode the data models presented in Section 4 and Section 5 2435 into JSON and provides some example encodings. The JSON examples may 2436 contain ellipses (...) to represent additional properties or elements 2437 that have been omitted in order to make the examples more concise. 2439 6.1. JSON-RPC Binding 2441 The JSON-RPC [JSON-RPC] protocol consists of two basic objects, 2442 Request and Response: 2444 o The JSON-RPC Request object encapsulates a PAWS functionality 2445 (operation) and the request message 2447 o The JSON-RPC Response object encapsulates a PAWS response message 2448 and Error element 2450 The Database and device MUST support JSON-RPC 2.0 encoding, with the 2451 restriction that the "id" parameter in the messages MUST be a string. 2452 The device should generate the "id" uniquely enough to allow the use 2453 of JSON-RPC batch. 2455 The JSON-RPC Request for PAWS has the following form: 2457 { 2458 "jsonrpc": "2.0", 2459 "method": "spectrum.paws.methodName", 2460 "params": , 2461 "id": "idString" 2462 } 2464 where "method" is the name of a PAWS functionality (operation), and 2465 represents one of the PAWS request messages associated 2466 with the method (see Section 4.3 through Section 4.6). Method names 2467 are defined with the prefix, "spectrum.paws.". 2469 The non-error JSON-RPC Response for PAWS has the following form: 2471 { 2472 "jsonrpc": "2.0", 2473 "result": , 2474 "id": "idString" 2475 } 2477 where represents one of the PAWS response messages 2478 associated with the method, and "id" is copied from the request. 2480 The error JSON-RPC Response for PAWS has the following form: 2482 { 2483 "jsonrpc": "2.0", 2484 "error": { 2485 "code": -102, 2486 "message": "An appropriate error message.", 2487 "data": { ... } 2488 }, 2489 "id": "idString" 2490 } 2492 where the "error" object corresponds to the Error Element 2493 (Section 5.17), and "code" is an error code described in the same 2494 section. The Database SHOULD attempt to use the most specific 2495 applicable PAWS error code. When an accurate one is not available, 2496 it SHOULD fall back to standard JSONRPC error codes as defined in 2497 JSONRPC specification. For example, if the Database receives invalid 2498 JSON from the device, it should respond with "-32700", signifying a 2499 parse error. As a last resort, the Database MAY send a suitable HTTP 2500 5xx response. 2502 6.1.1. Method Names 2504 Table 2 defines the method name, request object, and response object 2505 for each functionality defined in Protocol Functionalities 2506 (Section 4). 2508 +------------------------+--------------------+---------------------+ 2509 | Method Name | Request | Response | 2510 +------------------------+--------------------+---------------------+ 2511 | spectrum.paws.init | INIT_REQ (Section | INIT_RESP (Section | 2512 | | 4.3.1) | 4.3.2) | 2513 | spectrum.paws.register | REGISTRATION_REQ | REGISTRATION_RESP | 2514 | | (Section 4.4.1) | (Section 4.4.2) | 2515 | spectrum.paws.getSpect | AVAIL_SPECTRUM_REQ | AVAIL_SPECTRUM_RESP | 2516 | rum | (Section 4.5.1) | (Section 4.5.2) | 2517 | spectrum.paws.getSpect | AVAIL_SPECTRUM_BAT | AVAIL_SPECTRUM_BATC | 2518 | rumBatch | CH_REQ (Section | H_RESP (Section | 2519 | | 4.5.3) | 4.5.4) | 2520 | spectrum.paws.notifySp | SPECTRUM_USE_NOTIF | SPECTRUM_USE_RESP | 2521 | ectrumUse | Y (Section 4.5.5) | (Section 4.5.6) | 2522 | spectrum.paws.verifyDe | DEV_VALID_REQ | DEV_VALID_RESP | 2523 | vice | (Section 4.6.1) | (Section 4.6.2) | 2524 +------------------------+--------------------+---------------------+ 2526 Table 2 2528 6.1.2. JSON Encoding of Data Models 2530 JSON [RFC7159] encoding of the data models described in Section 4 and 2531 Section 5 is straightforward: 2533 o Each data model describes the contents of a JSON object 2535 o Each parameter of a data model corresponds to a member of the 2536 corresponding JSON object: 2538 * The parameter name of the data model is the same as the member 2539 name of the JSON object 2541 * The parameter data type describes the type of the member value 2543 o Primitive types map to JSON type, as described in Section 4, 2544 repeated here: 2546 string: A JSON string, restricted to UTF-8 encoding 2548 int: A JSON number, without a fractional or exponent part 2549 float: A JSON number 2551 boolean: One of the JSON values, true or false 2553 o The list type maps to a JSON array, except that all values in the 2554 array are of the same type 2556 o When the parameter data type refers to another data model, that 2557 data model describes a nested JSON object 2559 o The encoded JSON object for each of the Request and Response 2560 message listed in the Method Names Table (Table 2) also includes 2561 the following members: 2563 type: The name of the message, e.g., "INIT_REQ" 2565 version: The PAWS version, e.g., "1.0" 2567 See the following sections for examples. 2569 6.2. Example Encoding: spectrum.paws.init Method 2571 An example of the "spectrum.paws.init" JSON-RPC request is shown 2572 below; 2574 { 2575 "jsonrpc": "2.0", 2576 "method": "spectrum.paws.init", 2577 "params": { 2578 "type": "INIT_REQ", 2579 "version": "1.0", 2580 "deviceDesc": { 2581 "serialNumber": "XXX", 2582 "fccId": "YYY", 2583 "rulesetIds": ["FccTvBandWhiteSpace-2010"] 2584 }, 2585 "location": { 2586 "point": { 2587 "center": {"latitude": 37.0, "longitude": -101.3} 2588 } 2589 } 2590 }, 2591 "id": "xxxxxx" 2592 } 2594 An example of the corresponding JSON-RPC response is shown below: 2596 { 2597 "jsonrpc": "2.0", 2598 "result": { 2599 "type": "INIT_RESP", 2600 "version": "1.0", 2601 "rulesetInfos": [ 2602 { 2603 "authority": "us", 2604 "rulesetId": "FccTvBandWhiteSpace-2010", 2605 "maxLocationChange": 100, 2606 "maxPollingSecs": 86400 2607 } 2608 ] 2609 }, 2610 "id": "xxxxxx" 2611 } 2613 6.3. Example Encoding: spectrum.paws.getSpectrum Method 2615 An example of the "spectrum.paws.getSpectrum" JSON-RPC request is 2616 shown below: 2618 { 2619 "jsonrpc": "2.0", 2620 "method": "spectrum.paws.getSpectrum", 2621 "params": { 2622 "type": "AVAIL_SPECTRUM_REQ", 2623 "version": "1.0", 2624 "deviceDesc": { 2625 "serialNumber": "XXX", 2626 "fccId": "YYY", 2627 "rulesetIds": ["FccTvBandWhiteSpace-2010"] 2628 }, 2629 "location": { 2630 "point": { 2631 "center": {"latitude": 37.0, "longitude": -101.3} 2632 } 2633 }, 2634 "antenna": {"height": 10.2, "heightType": "AGL"} 2635 }, 2636 "id": "xxxxxx" 2637 } 2639 The following example "spectrum.paws.getSpectrum" JSON-RPC response 2640 contains: 2642 o A schedule with two time ranges 2643 o A spectrum profile for one resolution bandwidth (6 MHz) 2645 o The power levels for two frequency segments are shown: 2647 * From 518 MHz to 542 MHz 2649 * From 620 MHz to 626 MHz 2651 o In practice, each "profiles" list contains (frequency, power) 2652 points to cover all frequencies governed by the associated 2653 ruleset. See the Spectrum (Section 5.11) section for a more 2654 detailed discussion on the representation. 2656 { 2657 "jsonrpc": "2.0", 2658 "result": { 2659 "type": "AVAIL_SPECTRUM_RESP", 2660 "version": "1.0", 2661 "timestamp": "2013-03-02T14:30:21Z", 2662 "deviceDesc": { 2663 "serialNumber": "XXX", 2664 "fccId": "YYY", 2665 "rulesetIds": ["FccTvBandWhiteSpace-2010"] 2666 }, 2667 "spectrumSpecs": [ 2668 { 2669 "rulesetInfo": { 2670 "authority": "us", 2671 "rulesetId": "FccTvBandWhiteSpace-2010" 2672 }, 2673 "needsSpectrumReport": false, 2674 "spectrumSchedules": [ 2675 { 2676 "eventTime": { 2677 "startTime": "2013-03-02T14:30:21Z", 2678 "stopTime": "2013-03-02T20:00:00Z" 2679 }, 2680 "spectra": [ 2681 { 2682 "resolutionBwHz": 6e6, 2683 "profiles": [ 2684 ... 2685 [ 2686 {"hz":5.18e8, "dbm":30.0}, 2687 {"hz":5.36e8, "dbm":30.0}, 2688 {"hz":5.36e8, "dbm":36.0}, 2689 {"hz":5.42e8, "dbm":36.0} 2690 ], 2692 [ 2693 {"hz":6.20e8, "dbm":30.0}, 2694 {"hz":6.26e8, "dbm":30.0} 2695 ], 2696 ... 2697 ] 2698 } 2699 ] 2700 }, 2701 { 2702 "eventTime": { 2703 "startTime": "2013-03-02T22:00:00Z", 2704 "stopTime": "2013-03-03T14:30:21Z" 2705 }, 2706 "spectra": [ 2707 ... 2708 ] 2709 } 2710 ] 2711 } 2712 ] 2713 }, 2714 "id": "xxxxxx" 2715 } 2717 The following example "spectrum.paws.getSpectrum" JSON-RPC response 2718 includes a spectrum profile that contains specifications for two 2719 different bandwidth resolutions (6 MHz and 100 kHz): 2721 { 2722 "jsonrpc": "2.0", 2723 "result": { 2724 "type": "AVAIL_SPECTRUM_RESP", 2725 "version": "1.0", 2726 "timestamp": "2013-03-02T14:30:21Z", 2727 "deviceDesc": { 2728 "serialNumber": "XXX", 2729 ... 2730 }, 2731 "spectrumSpecs": [ 2732 { 2733 "rulesetInfo": { 2734 "authority": "xx", 2735 ... 2736 }, 2737 "needsSpectrumReport": false, 2738 "spectrumSchedules": [ 2739 { 2740 "eventTime": { 2741 "startTime": "2013-03-02T14:30:21Z", 2742 "stopTime": "2013-03-02T20:00:00Z" 2743 }, 2744 "spectra": [ 2745 { 2746 "resolutionBwHz": 6e6, 2747 "profiles": [ 2748 ... 2749 [ 2750 {"hz":5.18e8, "dbm":30.0}, 2751 {"hz":5.36e8, "dbm":30.0}, 2752 {"hz":5.36e8, "dbm":36.0}, 2753 {"hz":5.42e8, "dbm":36.0} 2754 ], 2755 [ 2756 {"hz":6.20e8, "dbm":30.0}, 2757 {"hz":6.26e8, "dbm":30.0} 2758 ], 2759 ... 2760 ] 2761 }, 2762 { 2763 "resolutionBwHz": 1e5, 2764 "profiles": [ 2765 ... 2766 [ 2767 {"hz":5.18e8, "dbm":27.0}, 2768 {"hz":5.36e8, "dbm":27.0}, 2769 {"hz":5.36e8, "dbm":30.0}, 2770 {"hz":5.42e8, "dbm":30.0} 2771 ], 2772 [ 2773 {"hz":6.20e8, "dbm":27.0}, 2774 {"hz":6.26e8, "dbm":27.0} 2775 ], 2776 ... 2777 ] 2778 } 2779 ] 2780 }, 2781 { 2782 "eventTime": { 2783 "startTime": "2013-03-02T22:00:00Z", 2784 "stopTime": "2013-03-03T14:30:21Z" 2785 }, 2786 "spectra": [ 2787 ... 2789 ] 2790 } 2791 ] 2792 } 2793 ] 2794 }, 2795 "id": "xxxxxx" 2796 } 2798 6.4. Example Encoding: DeviceOwner vCard 2800 The DeviceOwner (Section 5.5) data model contains member values that 2801 are JSON encodings of vCard, as described in "jCard: The JSON format 2802 for vCard" [RFC7095]. An example fragment is provided below: 2804 { 2805 ... 2806 "deviceOwner": { 2807 "owner": [ 2808 "vcard", [ 2809 ["version", {}, "text", "4.0"], 2810 ["kind", {}, "text", "org"], 2811 ["fn", {}, "text", "Racafrax, Inc."] 2812 ] 2813 ], 2814 "operator": [ 2815 "vcard", [ 2816 ["version", {}, "text", "4.0"], 2817 ["fn", {}, "text", "John Frax"], 2818 ["adr", {}, "text", 2819 ["", "", "100 Main Street", 2820 "Summersville", "CA", "90034", "USA" 2821 ] 2822 ], 2823 ["tel", {}, "uri", "tel:+1-213-555-1212"], 2824 ["email", {}, "text", "j.frax@rackafrax.com"] 2825 ] 2826 ] 2827 } 2828 } 2830 7. HTTPS Binding 2832 This section describes the use of "HTTP Over TLS" [RFC2818] (HTTPS) 2833 as the transfer mechanism for PAWS. TLS provides message integrity 2834 and confidentiality between the Master Device and the Database, but 2835 only when best current practices are adopted, including use of 2836 recommended cipher suites and modes of operation. Consequently, to 2837 improve PAWS security and interoperability, implementations of the 2838 Database and Master Device MUST follow best current practices defined 2839 by Recommendations for Secure Use of TLS and DTLS 2840 [I-D.ietf-uta-tls-bcp]. 2842 Depending on prior relationship between a database and device, the 2843 server MAY require client authentication, as described in the 2844 "Transport Layer Security (TLS) Protocol" [RFC5246], to authenticate 2845 the device. When client authentication is required, the database 2846 MUST specify, by prior arrangement, acceptable root Certificate 2847 Authorities (CAs) to serve as trust anchors for device certificates. 2849 To enable databases to handle large numbers of requests from large 2850 numbers of devices, the Database MAY support and devices SHOULD 2851 support "Stateless TLS Session Resumption" [RFC5077]. 2853 A PAWS request message is carried in the body of an HTTP POST 2854 request. A PAWS response message is carried in the body of an HTTP 2855 response. A PAWS response SHOULD include a Content-Length header. 2857 The POST method is the only method REQUIRED for PAWS. If a database 2858 chooses to support GET, it MUST be an escaped URI, but the encoding 2859 of the URI is outside the scope of this document. The database MAY 2860 refuse to support the GET request by returning an HTTP error code, 2861 such as 405 (method not allowed). 2863 The Database MAY redirect a PAWS request by returning a HTTP 3xx 2864 response (as defined by "HTTP/1.1: Semantics and Content" [RFC7231], 2865 Section 6.4). The Database MUST provide the redirect URI in the 2866 Location header of the 3xx response, and the device MUST handle 2867 redirects by using the Location header provided by the Database. 2868 When redirecting, the device MUST observe the delay indicated by the 2869 Retry-After header. The device MUST authenticate the Database that 2870 returns the redirect response before following the redirect. Also, 2871 the device MUST authenticate the Database indicated in the redirect. 2872 Since the device may communicate with a Database (which it 2873 authenticated) without user interaction, when the response code is 2874 301 (Moved Permanently), the device MAY redirect without asking a 2875 user for confirmation, even thought it is in response to an HTTP POST 2876 method. 2878 The Database SHOULD use HTTP status code "307 Temporary Redirect" to 2879 indicate that the device SHOULD resubmit the same request to an 2880 alternate URI. The device MAY revert to the original URI for the 2881 very next request, or MAY continue to use the alternate URI for a 2882 period of time, e.g.,: 2884 o For the remainder of its session, or 2885 o For a fixed period of time, or 2887 o Until power cycled, or 2889 o Until it receives another redirect 2891 However, the device does not need to modify its stored list of URIs. 2893 For a minimum of two weeks before the URI of the Database changes 2894 permanently, it MUST use the database-change (DbUpdateSpec 2895 (Section 5.7)) mechanism to notify devices, as described in the 2896 Configuration Update portion of the Database Discovery (Section 4.1) 2897 section. After the Database has moved, requests to the original URI 2898 MAY return HTTP status code "301 Moved Permanently" to indicate that 2899 the device SHOULD resubmit the request, and all future requests, to 2900 the indicated alternate URI. 2902 8. Extensibility 2904 This section describes procedures for extending PAWS. No extensions 2905 should be made that would return sensitive device-specific 2906 information in Database responses. 2908 8.1. Defining Ruleset Identifiers 2910 A ruleset represents a set of device-side requirements for which the 2911 device has been certified. It typically corresponds to, but is not 2912 limited to, a set of rules that govern a specific set of radio 2913 spectrum for a regulatory domain. 2915 Ruleset identifiers are defined and registered in the Ruleset ID 2916 Registry following the procedure in Section 9.1. Ruleset ID values 2917 MUST conform to the ruleset-id ABNF. If the Ruleset ID requires 2918 additional parameters, they are registered in the PAWS Parameters 2919 Registry, as described by Section 9.2. 2921 ruleset-id = 1*64ruleset-char 2922 ruleset-char = ALPHA / DIGIT / "_" / "." 2924 When defining a Ruleset ID: 2926 o It can be useful for the identifier to be descriptive of the set 2927 of rules that allow a device to operate within one or more 2928 regulatory domains. For example, it might include the name of a 2929 regulatory body or a certification process. 2931 o The identifier SHOULD include some sort of version information, 2932 such as a year and/or version number. 2934 o The maximum length of the identifier is 64 octets. 2936 8.2. Defining New Message Parameters 2938 New request or response parameters for use with PAWS are defined and 2939 registered in the parameters registry following the procedure in 2940 Section 9.2. 2942 Parameter names MUST conform to the param-name ABNF and parameter 2943 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2944 to the syntax of an existing parameter). 2946 param-name = 1*64name-char 2947 name-char = ALPHA / DIGIT / "_" 2949 Parameter names use lowerCamelCase by convention. The maximum length 2950 of a name is 64 octets. 2952 Unregistered vendor-specific parameter extensions that are not 2953 commonly applicable, and are specific to the implementation details 2954 of the Database where they are used SHOULD use a vendor-specific 2955 prefix that is not likely to conflict with other registered values 2956 (e.g., begin with 'companyname'). 2958 8.3. Defining Additional Error Codes 2960 Additional error codes can be registered to extend the set listed in 2961 Section 5.17, following the procedures in Section 9.3. If the error 2962 code requires additional response parameters, they are registered in 2963 the PAWS Parameters Registry, as described by Section 9.2. 2965 By convention, the error code is a negative integer value, using one 2966 of the range of values defined in Error Codes (Section 5.17). If an 2967 appropriate category does not exist, a value from a different range 2968 may be used. 2970 9. IANA Considerations 2972 [RFC Editor/IANA: Please replace "[[ this document ]]" with the RFC 2973 number of this document as indicated below, and remove this note 2974 prior to publication] 2976 There are three registries associated with PAWS: 2978 o PAWS Ruleset ID Registry (Section 9.1) 2980 o PAWS Parameter Registry (Section 9.2) 2981 o PAWS Error Code Registry (Section 9.3) 2983 Prior to registration, the registrant is encouraged to post to the 2984 paws@ietf.org mailing list, including the specification or its draft, 2985 to get early feedback. 2987 All registries use the Specification Required policy [RFC5226], with 2988 a Designated Expert appointed by the IESG. Specific criteria that 2989 the Designated Expert should use in assessing registrations are given 2990 below in the description of each registry. The Designated Expert 2991 should take advice from the community through the paws@ietf.org 2992 mailing list, and the registrant is encouraged to post to the mailing 2993 list before formally requesting the registration from IANA. The 2994 intention is that new registrations will be accompanied by a 2995 published specification. But in order to allow for the allocation of 2996 values prior to publication of the specification, the Designated 2997 Expert can approve allocations once it seems clear that the 2998 specification will be published. Upon approval, IANA will post each 2999 registration template that is not included in the text of an RFC. 3001 9.1. PAWS Ruleset ID Registry 3003 This specification establishes the PAWS Ruleset ID Registry. 3005 Ruleset type names for inclusion in PAWS messages are registered on 3006 the advice of one or more Designated Experts, with Specification 3007 Required [RFC5226]. The specification must include a reference to 3008 the regulatory domain to which it applies. To increase 3009 interoperability, it is more desirable to have fewer rulesets than to 3010 have many rulesets with small variations. Consequently, the 3011 Designated Expert should avoid duplication and should encourage the 3012 registrant to look for alternatives if there are only small 3013 variations from an existing ruleset. The Designated Expert should 3014 ensure that the proposed registration is complete with respect to its 3015 associated regulatory domain and may seek an expert familiar with 3016 those rules to participate in the review on the paws@ietf.org mailing 3017 list. 3019 The PAWS Ruleset ID Registry will include the following: 'Ruleset 3020 identifier', 'Specification document(s)', and 'Template'. The 3021 Template column will include links to the registration templates, 3022 either posted by IANA or the relevant sections of RFCs. 3024 9.1.1. Registration Template 3026 Ruleset identifier: The name of the ruleset. See [[ this document 3027 ]], Section 8.1 for the format requirements of this identifier. 3029 Specification document(s): Reference to the document that specifies 3030 the parameter, preferably including a URI that can be used to 3031 retrieve a copy of the document. An indication of the relevant 3032 sections also may be included, but is not required. 3034 Additional Parameter Requirements: Listing of additional parameter 3035 requirements to associate with the ruleset. Note that new 3036 parameters are registered separately in the PAWS Parameters 3037 Registry, as described by Section 8.2. Two types of additional 3038 parameter requirements are: 3040 * Addition of new parameters to existing structures, or 3041 modification of the REQUIRED and OPTIONAL requirements for 3042 existing parameters. 3044 * Modification of requirements to existing parameter values. 3046 For adding new parameters or modifying requirements of existing 3047 parameters, the registration should include a table for each 3048 affected structure that lists the structure's parameter changes. 3049 Each table should include a structure name in its heading and have 3050 the following columns: 3052 Parameter name: Name of the parameter added or modified. 3054 Type: Data type of the parameter value. 3056 Requirement: Whether the parameter is REQUIRED or OPTIONAL for 3057 the ruleset. 3059 Notes: Any additional notes that might be useful to implementors. 3061 For modifying requirements to existing parameter values, the 3062 registration should include a table for each affected structure 3063 that lists the structure's parameter changes. Each table should 3064 include a structure name in its heading and have the following 3065 columns: 3067 Parameter name: Name of the parameter. 3069 Type: Data type of the parameter value. 3071 Additional requirements: Additional requirements on the parameter 3072 value. 3074 IANA will post each registration template that is not included in the 3075 text of an RFC. 3077 Note that the Additional Parameter Requirements section can be quite 3078 extensive, so it will not appear directly in the IANA Ruleset ID 3079 Registry table. The table, however, does contain a link to the full 3080 registration template for easy access to the additional requirements. 3082 9.1.2. Initial Registry Contents 3084 The PAWS Ruleset ID Registry enables protocol extensibility to 3085 support any regulatory domain and ruleset. The initial contents of 3086 the registry, however, include only FCC-specific and ETSI-specific 3087 entries, because, as of this writing, they are the only regulatory 3088 domains that have finalized rules. There is no intent to restrict 3089 the protocol to any particular set of authorities. 3091 The initial contents of the PAWS Ruleset ID Registry are listed 3092 below; each section corresponds to a single entry in the registry. 3094 9.1.2.1. Federal Communications Commission (FCC) 3096 For the additional parameters that start with the "fcc" prefix, see 3097 PAWS Parameters Registry Initial Contents (Section 9.2.2) for more 3098 information. 3100 Ruleset identifier: FccTvBandWhiteSpace-2010 3102 Specification document(s): This ruleset refers to the FCC rules for 3103 TV-band White Space operations established in the Code of Federal 3104 Regulations (CFR), Title 47, Part 15, Subpart H [FCC-CFR47-15H]. 3106 Additional Parameter Requirements 3108 Each of the following tables defines additional parameters for the 3109 indicated PAWS message. Note that the Requirement column lists FCC, 3110 not PAWS, requirements/optionality rules. 3112 The FCC requires registration of "Fixed Devices". Additionally, 3113 deviceOwner is required in the registration request: 3115 Registration Request (Section 4.4.1) 3117 +-------------+-------------------+-------------+-------------------+ 3118 | Parameter | Type | Requirement | Notes | 3119 | Name | | | | 3120 +-------------+-------------------+-------------+-------------------+ 3121 | deviceOwner | DeviceOwner | REQUIRED | For registering | 3122 | | (Section 5.5) | | Fixed Devices | 3123 +-------------+-------------------+-------------+-------------------+ 3124 Available Spectrum Request (Section 4.5.1) 3126 +---------------+-----------------------------+-------------+-------+ 3127 | Parameter | Type | Requirement | Notes | 3128 | Name | | | | 3129 +---------------+-----------------------------+-------------+-------+ 3130 | deviceDesc | DeviceDescriptor (Section | REQUIRED | | 3131 | | 5.2) | | | 3132 +---------------+-----------------------------+-------------+-------+ 3134 Available Spectrum Batch Request (Section 4.5.3) 3136 +---------------+-----------------------------+-------------+-------+ 3137 | Parameter | Type | Requirement | Notes | 3138 | Name | | | | 3139 +---------------+-----------------------------+-------------+-------+ 3140 | deviceDesc | DeviceDescriptor (Section | REQUIRED | | 3141 | | 5.2) | | | 3142 +---------------+-----------------------------+-------------+-------+ 3144 DeviceDescriptor (Section 5.2) 3146 +-------------------+--------+-------------+------------------------+ 3147 | Parameter Name | Type | Requirement | Notes | 3148 +-------------------+--------+-------------+------------------------+ 3149 | serialNumber | string | REQUIRED | Specifies a device's | 3150 | | | | serial number. See [[ | 3151 | | | | this document ]], | 3152 | | | | Section 5.2. | 3153 | fccId | string | REQUIRED | Specifies a device's | 3154 | | | | FCC certification ID | 3155 | | | | (Section 9.2.2.1). | 3156 | fccTvbdDeviceType | string | REQUIRED | Specifies the FCC | 3157 | | | | Device Type (Section | 3158 | | | | 9.2.2.2) of TV-band | 3159 | | | | White Space device, as | 3160 | | | | defined by the FCC | 3161 | | | | rules. | 3162 +-------------------+--------+-------------+------------------------+ 3164 The following table lists additional requirements for DeviceOwner 3165 (Section 5.5) parameter values. 3167 DeviceOwner (Section 5.5) 3169 +-----------+-------+-----------------------------------------------+ 3170 | Parameter | Type | Additional Requirement | 3171 | Name | | | 3172 +-----------+-------+-----------------------------------------------+ 3173 | owner | vCard | The owner is required to contain the | 3174 | | | formatted name of an individual or | 3175 | | | organization using the "fn" property. When | 3176 | | | the name is that of an organization, the | 3177 | | | entry also is required to contain the "kind" | 3178 | | | property, with a value of "org". | 3179 | operator | vCard | The operator entry is required to contain the | 3180 | | | following properties for the contact person | 3181 | | | responsible for the device's operation: "fn", | 3182 | | | "adr", "tel", and "email". | 3183 +-----------+-------+-----------------------------------------------+ 3185 9.1.2.2. European Telecommunications Standards Institute (ETSI) 3187 For the additional parameters that start with the "etsi" prefix, see 3188 PAWS Parameters Registry Initial Contents (Section 9.2.2) for more 3189 information. 3191 Ruleset identifier: ETSI-EN-301-598-1.1.1 3193 Specification document(s): This ruleset refers to the ETSI 3194 Harmonised Standard [ETSI-EN-301-598] established by ETSI. 3196 Additional Parameter Requirements 3198 Each of the following tables defines additional parameters for the 3199 indicated PAWS message. Note that the Requirement column lists ETSI, 3200 not PAWS, requirements/optionality rules, 3201 DeviceDescriptor (Section 5.2) 3203 +-------------------------+-------+-------------+-------------------+ 3204 | Parameter Name | Type | Requirement | Notes | 3205 +-------------------------+-------+-------------+-------------------+ 3206 | serialNumber | strin | REQUIRED | Specifies a | 3207 | | g | | device's serial | 3208 | | | | number. See [[ | 3209 | | | | this document ]], | 3210 | | | | Section 5.2. | 3211 | manufacturerId | strin | REQUIRED | Specifies a | 3212 | | g | | device's | 3213 | | | | manufacturer's | 3214 | | | | identifier. See | 3215 | | | | [[ this document | 3216 | | | | ]], Section 5.2. | 3217 | modelId | strin | REQUIRED | Specifies a | 3218 | | g | | device's model | 3219 | | | | identifier. See | 3220 | | | | [[ this document | 3221 | | | | ]], Section 5.2. | 3222 | etsiEnDeviceType | strin | REQUIRED | Specifies the | 3223 | | g | | device's ETSI | 3224 | | | | device type | 3225 | | | | (Section | 3226 | | | | 9.2.2.3). | 3227 | etsiEnDeviceEmissionsCl | strin | REQUIRED | Specifies the | 3228 | ass | g | | device's ETSI | 3229 | | | | device emissions | 3230 | | | | class (Section | 3231 | | | | 9.2.2.4). | 3232 | etsiEnTechnologyId | strin | REQUIRED | Specifies the | 3233 | | g | | device's ETSI | 3234 | | | | technology ID | 3235 | | | | (Section | 3236 | | | | 9.2.2.5). | 3237 | etsiEnDeviceCategory | strin | REQUIRED | Specifies the | 3238 | | g | | device's ETSI | 3239 | | | | device category | 3240 | | | | (Section | 3241 | | | | 9.2.2.6). | 3242 +-------------------------+-------+-------------+-------------------+ 3243 AVAIL_SPECTRUM_REQ (Section 4.5.1) 3245 +-------------+--------+-------------+------------------------------+ 3246 | Parameter | Type | Requirement | Notes | 3247 | Name | | | | 3248 +-------------+--------+-------------+------------------------------+ 3249 | requestType | string | OPTIONAL | Modifies the available- | 3250 | | | | spectrum request type. If | 3251 | | | | specified, the only valid | 3252 | | | | value is, "Generic Slave", | 3253 | | | | and the Database is required | 3254 | | | | to respond with generic | 3255 | | | | operating parameters for any | 3256 | | | | Slave Device. | 3257 +-------------+--------+-------------+------------------------------+ 3259 Available Spectrum Batch Request (Section 4.5.3) 3261 +-------------+--------+-------------+------------------------------+ 3262 | Parameter | Type | Requirement | Notes | 3263 | Name | | | | 3264 +-------------+--------+-------------+------------------------------+ 3265 | requestType | string | OPTIONAL | Modifies the available- | 3266 | | | | spectrum request type. If | 3267 | | | | specified, the only valid | 3268 | | | | value is, "Generic Slave", | 3269 | | | | and the Database is required | 3270 | | | | to respond with generic | 3271 | | | | operating parameters for any | 3272 | | | | Slave Device. | 3273 +-------------+--------+-------------+------------------------------+ 3275 The following tables define additional requirements for the 3276 DeviceDescriptor (Section 5.2) and RulesetInfo (Section 5.6) 3277 parameters that appear in the AVAIL_SPECTRUM_RESP (Section 4.5.2) and 3278 AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) messages. Note that this 3279 means the Database is modifying the DeviceDescriptor sent by the 3280 Master Device to return device-specific restrictions. 3282 DeviceDescriptor (Section 5.2) 3284 +--------------------------------+-------+----------+---------------+ 3285 | Parameter Name | Type | Requirem | Notes | 3286 | | | ent | | 3287 +--------------------------------+-------+----------+---------------+ 3288 | needsSpectrumReport | boole | REQUIRED | The Database | 3289 | | an | | is required | 3290 | | | | to set this | 3291 | | | | to true to | 3292 | | | | indicate that | 3293 | | | | the device | 3294 | | | | must report | 3295 | | | | spectrum | 3296 | | | | usage. | 3297 | maxTotalBwHz | float | REQUIRED | Specifies a | 3298 | | | | constraint on | 3299 | | | | total allowed | 3300 | | | | bandwidth. | 3301 | maxContiguousBwHz | float | REQUIRED | Specifies a | 3302 | | | | constraint on | 3303 | | | | total allowed | 3304 | | | | contiguous | 3305 | | | | bandwidth. | 3306 | etsiEnSimultaneousChannelOpera | strin | REQUIRED | Specifies a | 3307 | tionRestriction | g | | constraint on | 3308 | | | | simultaneous | 3309 | | | | channel | 3310 | | | | operation | 3311 | | | | (Section | 3312 | | | | 9.2.2.7). If | 3313 | | | | it is not | 3314 | | | | provided, the | 3315 | | | | default value | 3316 | | | | is "0". | 3317 +--------------------------------+-------+----------+---------------+ 3319 RulesetInfo (Section 5.6) 3321 +-------------------+-------+-------------+-------------------------+ 3322 | Parameter Name | Type | Requirement | Notes | 3323 +-------------------+-------+-------------+-------------------------+ 3324 | maxLocationChange | float | OPTIONAL | Specifies a constraint | 3325 | | | | on maximum location | 3326 | | | | changes. | 3327 +-------------------+-------+-------------+-------------------------+ 3329 9.2. PAWS Parameters Registry 3331 This specification establishes the PAWS Parameters Registry. 3333 Additional parameters for inclusion in PAWS requests, responses, or 3334 sub-messages are registered on the advice of one or more Designated 3335 Experts, with Specification Required [RFC5226]. 3337 The Designated Expert should avoid duplication, i.e., avoid adding a 3338 new parameter when an existing one suffices. When a set of 3339 parameters is added in support of a new ruleset (Section 9.1), the 3340 parameters should share a common prefix that reflects the ruleset ID. 3341 The prefix may be omitted, of course, if a parameter has more general 3342 applicability. Similarly, when a parameter is not associated with a 3343 ruleset, the Designated Expert should ensure that the parameter name 3344 does not have a prefix used by existing ruleset parameters (e.g., 3345 "fcc", "etsi") or are the initials of an organization that has not 3346 yet registered anything, but reasonably might. 3348 The PAWS Parameters Registry will include the following: 'Parameter 3349 name', 'Parameter usage location', and 'Specification document(s)'. 3351 9.2.1. Registration Template 3353 Parameter name: The name of the parameter (e.g., "example"). 3355 Parameter usage location: The location(s) where the parameter can be 3356 used. The possible locations are the named structures defined in 3357 Protocol Functionalities (Section 4) and Protocol Parameters 3358 (Section 5). 3360 Specification document(s): Reference to the document that specifies 3361 the parameter, preferably including a URI that can be used to 3362 retrieve a copy of the document. An indication of the relevant 3363 sections also may be included, but is not required. 3365 9.2.2. Initial Registry Contents 3367 The PAWS Parameters Registry enables protocol extensibility to 3368 support any regulatory domain and ruleset. The initial contents of 3369 the registry, however, include only FCC-specific and ETSI-specific 3370 entries, because, as of this writing, they are the only regulatory 3371 domains that have established rules. There is no intent to restrict 3372 the protocol to any particular set of authorities. 3374 The PAWS Parameters Registry's initial contents are listed below; 3375 each section corresponds to a row of the registry. 3377 9.2.2.1. FCC ID 3379 Parameter name: fccId 3381 Parameter usage location: DeviceDescriptor (Section 5.2) 3383 Specification document(s): [[ this document ]] Specifies the 3384 device's FCC certification identifier. A valid FCC ID is limited 3385 to 19 characters in the ASCII value range, as proposed in FCC 3386 Administration Topics Review [FCC-Review-2012-10]. For the 3387 purposes of the PAWS protocol, the maximum length of the fccId 3388 value is 32 octets. 3390 9.2.2.2. FCC Device Type 3392 Parameter name: fccTvbdDeviceType 3394 Parameter usage location: DeviceDescriptor (Section 5.2) 3396 Specification document(s): [[ this document ]] Specifies the TV Band 3397 White Space device type, as defined by the FCC. Valid values are 3398 "FIXED", "MODE_1", "MODE_2". 3400 9.2.2.3. ETSI Device Type 3402 Parameter name: etsiEnDeviceType 3404 Parameter usage location: DeviceDescriptor (Section 5.2) 3406 Specification document(s): Specifies the White Space Device type, as 3407 defined by the ETSI Harmonised Standard [ETSI-EN-301-598]. Valid 3408 values are single-letter strings, such as "A", "B", etc. Consult 3409 the documentation for details about the device types. 3411 9.2.2.4. ETSI Device Emissions Class 3413 Parameter name: etsiEnDeviceEmissionsClass 3415 Parameter usage location: DeviceDescriptor (Section 5.2) 3417 Specification document(s): Specifies the White Space Device 3418 emissions class, as defined by the ETSI Harmonised Standard 3419 [ETSI-EN-301-598], that characterises the out-of-block emissions 3420 of the device. The values are represented by numeric strings, 3421 such as "1", "2", "3", etc. Consult the documentation for details 3422 about emissions classes 3424 9.2.2.5. ETSI Technology Identifier 3426 Parameter name: etsiEnTechnologyId 3428 Parameter usage location: DeviceDescriptor (Section 5.2) 3430 Specification document(s): Specifies the White Space Device 3431 technology identifier, as defined by the ETSI Harmonised Standard 3432 [ETSI-EN-301-598]. The maximum length of the string value is 64 3433 octets. Consult the documentation for valid values. 3435 9.2.2.6. ETSI Device Category 3437 Parameter name: etsiEnDeviceCategory 3439 Parameter usage location: DeviceDescriptor (Section 5.2) 3441 Specification document(s): Specifies the White Space Device 3442 category, as defined by the ETSI Harmonised Standard 3443 [ETSI-EN-301-598]. Valid values are the strings, "master" and 3444 "slave". It is case insensitive. 3446 9.2.2.7. ETSI Simultaneous Channel Operation Restriction 3448 Parameter name: etsiEnSimultaneousChannelOperationRestriction 3450 Parameter usage location: SpectrumSpec (Section 5.9) 3452 Specification document(s): Specifies the constraint on the device 3453 maximum total EIRP, as defined by the ETSI Harmonised Standard 3454 [ETSI-EN-301-598]. The values are represented by numeric strings, 3455 such as "0", "1", etc. Consult the documentation for the 3456 specification of the power constraint corresponding to each 3457 parameter value. 3459 9.3. PAWS Error Code Registry 3461 This specification establishes the PAWS Error Code Registry. 3463 Additional error codes for inclusion in PAWS error messages are 3464 registered on the advice of one or more Designated Experts, with 3465 Specification Required [RFC5226]. 3467 Error codes are intended to be used for automated error handling by 3468 devices. Before approval, the Designated Expert should consider 3469 whether a device would handle the new error code differently from an 3470 existing error code, or whether the difference could be communicated 3471 effectively to the end-user via the "reason" parameter of the Error 3472 (Section 5.17) object. 3474 The PAWS Error Code Registry will include the following: 'Code', 3475 'Name', 'Description and Additional parameters'. 3477 9.3.1. Registration Template 3479 Code: Integer value of the error code. The value MUST be an 3480 unassigned value in the range -32768 to 32767, inclusive. 3482 Name: Name of the error. 3484 Description and Additional parameters: Description of the error and 3485 its associated parameters, if any. It also lists additional 3486 parameters that are returned in the data portion of the error (See 3487 Section 5.17). New parameters MUST be registered separately in 3488 the PAWS Parameters Registry, as described by Section 9.2. 3490 9.3.2. Initial Registry Contents 3492 Initial registry contents are defined in the Table of Error Codes 3493 (Table 1). 3495 The registry will also include the error-code categories describing 3496 -100s, -200s, and -300s as a note (see Error Codes (Section 5.17)). 3498 10. Security Considerations 3500 PAWS is a protocol whereby a Master Device requests a schedule of 3501 available spectrum at its location (or location of its Slave Devices) 3502 before it (they) can operate using those frequencies. Whereas the 3503 information provided by the Database must be accurate and conform to 3504 the applicable ruleset, the Database cannot enforce, through the 3505 protocol, that a client device uses only the spectrum it provided. 3506 In other words, devices can put energy in the air and cause 3507 interference without asking the Database. Hence, PAWS security 3508 considerations do not include protection against malicious use of the 3509 White Space spectrum. For more detailed information on specific 3510 requirements and security considerations associated with PAWS, see 3511 "Protocol to Access White Space database: PAWS Use Cases and 3512 Requirements" [RFC6953]. 3514 By using PAWS, the Master Device and the Database expose themselves 3515 to the following risks: 3517 o Accuracy: The Master Device receives incorrect spectrum- 3518 availability information. 3520 o Privacy: 3522 o 3524 * An unauthorized entity intercepts identifying data for the 3525 Master Device or its Slave Devices, such as serial number and 3526 location. 3528 * Where databases are required to take device registrations and/ 3529 or maintain request logs, unauthorized access to such 3530 information. 3532 Protection from these risks depends on the success of the following 3533 steps: 3535 1. The Master Device must determine the address of a proper 3536 database. 3538 2. The Master Device must connect to the proper database. 3540 3. The Database must determine or compute accurate spectrum- 3541 availability information. 3543 4. PAWS messages must be transmitted unmodified between the Database 3544 and the Master Device. 3546 5. PAWS messages must be encrypted between the Database and the 3547 Master Device to prevent exposing private information. 3549 6. For a Slave Device, the spectrum-availability information also 3550 must be transmitted unmodified and secure between the Master 3551 Device and the Slave Device. 3553 7. When a Listing Server is required, any attack that would prevent 3554 reaching a Listing Server would result in all devices relying on 3555 that Listing Server ceasing their use of any Whitespace. 3557 8. No future extensions to PAWS can allow the return of sensitive 3558 information, such as device information or logs 3560 9. The Database must not allow unauthorized access to device 3561 information and request logs and should publish and implement 3562 privacy policies regarding their use. 3564 Of these, only steps 1, 2, 4, 5 and 8 are within the scope of this 3565 document. This document addresses Step 1 by allowing static 3566 provisioning of one or more trusted Databases; dynamic provisioning 3567 is out of scope. Step 3 is dependent on specific database 3568 implementations and rulesets and is outside the scope of this 3569 document. Step 6 requires a protocol between master and slave 3570 devices and is thus outside the scope of this document. 3572 Use of "HTTP Over TLS" [RFC2818], assuming the PKI used is not 3573 compromised, ensures steps 2, 4, and 5, as detailed in the following 3574 sections: 3576 o Assurance of Proper Database (Section 10.1) 3578 o Protection Against Modification (Section 10.2) 3580 o Protection Against Eavesdropping (Section 10.3) 3582 Any specification for an alternate transport MUST define mechanisms 3583 that ensure each of these steps. 3585 In addition to the privacy risks described above, information 3586 provided in DeviceDescriptor (Section 5.2) and DeviceOwner 3587 (Section 5.5), along with device location, may allow a Database 3588 administrator to track the activity and location of a device and its 3589 user over time. Risks of secondary use of such tracking information, 3590 including sharing with third parties, require out-of-band mitigation, 3591 such as public statements or contractual terms. Furthermore, while 3592 it is understandable that regulators require DeviceOwner information 3593 for higher-power fixed white space devices, for privacy concerns, 3594 regulators should not require DeviceOwner information for mobile 3595 devices. Similarly, regulators should require, and implementations 3596 should provide, device location at a level of granularity only as 3597 precise as necessary to support accurate database responses. 3599 10.1. Assurance of Proper Database 3601 This document assumes that the Database is contacted using a domain 3602 name or an IP address. Using HTTP over TLS, the Database 3603 authenticates its identity, either as a domain name or IP address, to 3604 the Master Device by presenting a certificate containing that 3605 identifier as a "subjectAltName" (i.e., as a dNSName or IP address). 3606 If the Master Device has external information as to the expected 3607 identity or credentials of the proper database (e.g., a certificate 3608 fingerprint), checks of the subjectAltName MAY be omitted. Note that 3609 in order for the presented certificate to be valid at the client, the 3610 client must be able to validate the certificate. In particular, the 3611 validation path of the certificate must end in one of the client's 3612 trust anchors, even if that trust anchor is the Database certificate 3613 itself. A Master Device should allow for the fact that a Database 3614 can change its certificate authorities (CAs) over time. 3616 10.2. Protection Against Modification 3618 To prevent a PAWS response message from being modified en route, 3619 messages must be transmitted over an integrity-protected channel. 3620 Using HTTP over TLS, the channel will be protected by appropriate 3621 cypher suites. 3623 10.3. Protection Against Eavesdropping 3625 Using HTTP over TLS, messages protected by appropriate cypher suites 3626 are also protected from eavesdropping or otherwise unrestricted 3627 reading by unauthorized parties en route. 3629 10.4. Client Authentication Considerations 3631 Although the Database can inform a device of available spectrum it 3632 can use, the Database cannot enforce that the Master Device uses any/ 3633 only those frequencies. Indeed, a malicious device can operate 3634 without ever contacting a database. Note also that, whereas a 3635 malicious device may send fraudulent SPECTRUM_USE_NOTIFY 3636 (Section 4.5.5) messages, in the regulatory domains that have 3637 established rules, such notifications do not change the available- 3638 spectrum answers, so no harm can result from such messages. 3639 Consequently, client authentication is not required for the core PAWS 3640 (although it may be required by specific regulatory domains). 3642 Depending on a prior relationship between a Database and Master 3643 Device, the Database MAY require client authentication. TLS provides 3644 client authentication, but there are some considerations: 3646 o The Database must nominate acceptable CAs and the Master Device 3647 must have a certificate rooted at one of those CAs. 3649 o As indicated in Section 3.2 of "HTTP Over TLS" [RFC2818], the TLS 3650 client authentication procedure only determines that the device 3651 has a certificate chain rooted in an appropriate CA (or a self- 3652 signed certificate). The database would not know what the client 3653 identity ought to be, unless it has some external source of 3654 information. Distribution and management of such information, 3655 including revocation lists, are outside the scope of this 3656 document. 3658 o Authentication schemes are secure only to the extent that secrets 3659 or certificates are kept secure. When there are a vast number of 3660 deployed devices using PAWS, the possibility that device keys will 3661 not leak becomes small. Implementations should consider how to 3662 manage the system in the eventuality that there is a leak. 3664 11. Contributors 3666 This document draws heavily from the following Internet Draft 3667 documents, draft-das-paws-protocol and draft-wei-paws-framework. The 3668 editor would like to specifically call out and thank the contributing 3669 authors of these two documents. 3671 Donald Joslyn 3672 Spectrum Bridge Inc. 3673 1064 Greenwood Blvd. 3674 Lake Mary, FL 32746 3675 U.S.A. 3676 Email: d.joslyn at spectrumbridge dot com 3678 Xinpeng Wei 3679 Huawei 3680 Phone: +86 13436822355 3681 Email: weixinpeng@huawei.com 3683 12. Acknowledgments 3685 The authors gratefully acknowledge the contributions of: Gabor Bajko, 3686 Ray Bellis, Teco Boot, Nancy Bravin, Rex Buddenberg, Gerald 3687 Chouinard, Stephen Farrell, Michael Fitch, Joel M. Halpern, Daniel 3688 Harasty, Michael Head, Jussi Kahtava, Warren Kumari, Kalle Kulsmanen, 3689 Paul Lambert, Andy Lee, Anthony Mancuso, Basavaraj Patil, Scott 3690 Probasco, Brian Rosen, Andy Sago, Peter Stanforth, John Stine, and 3691 Juan Carlos Zuniga. 3693 13. References 3695 13.1. Normative References 3697 [I-D.ietf-uta-tls-bcp] 3698 Sheffer, Y., Holz, R., and P. Saint-Andre, 3699 "Recommendations for Secure Use of TLS and DTLS", draft- 3700 ietf-uta-tls-bcp-06 (work in progress), October 2014. 3702 [JSON-RPC] 3703 "JSON-RPC 2.0 Specification", 3704 . 3706 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3707 Requirement Levels", BCP 14, RFC 2119, March 1997. 3709 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3711 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 3712 Internet: Timestamps", RFC 3339, July 2002. 3714 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3715 "Transport Layer Security (TLS) Session Resumption without 3716 Server-Side State", RFC 5077, January 2008. 3718 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3719 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3720 May 2008. 3722 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3723 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3725 [RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV 3726 Presence Information Data Format Location Object (PIDF-LO) 3727 Usage Clarification, Considerations, and Recommendations", 3728 RFC 5491, March 2009. 3730 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 3731 August 2011. 3733 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 3734 January 2014. 3736 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3737 Interchange Format", RFC 7159, March 2014. 3739 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3740 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3742 13.2. Informative References 3744 [ETSI-EN-301-598] 3745 European Telecommunication Standards Institute (ETSI), 3746 "ETSI EN 301 598 (V1.1.1): White Space Devices (WSD); 3747 Wireless Access Systems operating in the 470 MHz to 790 3748 MHz frequency band; Harmonized EN covering the essential 3749 requirements of article 3.2 of the R&TTE Directive", April 3750 2014, . 3754 [FCC-CFR47-15H] 3755 U. S. Government, "Electronic Code of Federal Regulations, 3756 Title 47, Part 15, Subpart H: Television Band Devices", 3757 December 2010, . 3760 [FCC-Review-2012-10] 3761 Federal Communications Commission, "Administration Topics 3762 Review", October 2012, 3763 . 3766 [I-D.ietf-geopriv-uncertainty] 3767 Thomson, M. and J. Winterbottom, "Representation of 3768 Uncertainty and Confidence in PIDF-LO", draft-ietf- 3769 geopriv-uncertainty-04 (work in progress), October 2014. 3771 [ISO3166-1] 3772 "Country Codes", 3773 . 3775 [RFC6953] Mancuso, A., Probasco, S., and B. Patil, "Protocol to 3776 Access White-Space (PAWS) Databases: Use Cases and 3777 Requirements", RFC 6953, May 2013. 3779 [WGS-84] National Imagery and Mapping Agency, "Department of 3780 Defense World Geodetic System 1984, Its Definition and 3781 Relationships with Local Geodetic Systems, NIMA TR8350.2 3782 Third Edition Amendment 1", January 2000, . 3785 Appendix A. Database Listing Server Support 3787 As discussed in Database Discovery (Section 4.1), some regulatory 3788 domains support the preconfiguration of devices with the URI of a 3789 listing server, to which devices can connect to obtain a list of 3790 databases certified by the regulatory domain. Regulatory domains may 3791 require the device to periodically contact the Database Listing 3792 Server to validate and/or update its list of certified databases. If 3793 the device is unable to validate its list of certified databases 3794 within the required period, regulatory rules may require the device 3795 to treat this inability as equivalent to the device having no 3796 available spectrum. 3798 A sample JSON response from a Database Listing Server might be 3799 represented as follows: 3801 { 3802 "lastUpdateTime": "2014-06-28T10:00:00Z", 3803 "maxRefreshMinutes": 1440 3804 "dbs": [ 3805 { 3806 "name": "Some Operator", 3807 "uris": [ 3808 { 3809 "uri": "https://example.some.operator.com", 3810 "protocol": "paws" 3811 }, 3812 ... 3813 ] 3814 }, 3815 ... 3816 ] 3817 } 3819 In parameters in this sample message are: 3821 lastUpdateTime The time at which the database entries were last 3822 updated. 3824 maxRefreshMinutes The maximum interval, expressed in minutes, that 3825 is allowed between device requests to the Database Listing Server. 3827 dbs A list of entries for certified databases, each containing the 3828 following 3830 name The name of the database operator. 3832 uris One or more URIs for each database, allowing a database to 3833 support more than one protocol. 3835 uri, protocol Each protocol supported by a certified database is 3836 associated with a separate URI (PAWS protocol URI shown). 3838 Appendix B. Changes / Author Notes. 3840 [RFC Editor: Remove this section before publication.] 3842 Changes from 15: 3844 o More precise language: "supports none of the ruleset" instead of 3845 "does not support any ruleset", where it makes sense. 3847 o Batch request: Change MAY to MUST when some locations are 3848 acceptable 3850 o Remove explicit mention of OCSP and leave it up the the TLS best 3851 practices draft 3853 o Define power levels are EIRP for consistency 3855 Changes from 14: 3857 o Clarified why spectrum-notify is "informational" 3859 o Clarified that device registration is typically only required for 3860 fixed devices 3862 o Global statement about timestamp format and must be UTC 3864 o Global statement about MISSING error returned, whether it's 3865 required by PAWS or ruleset 3867 o Clarified UNSUPPORTED error 3869 o Mandate that Database-change must be included in all responses a 3870 minimum of 2 weeks before change 3872 o Clarified that preconfigured values are ruleset specific 3873 (INIT_RESP) 3875 o Added reference to FCC ruleset for registration of Fixed Devices 3877 o Make deviceOwner and serialNumber optional at PAWS level and 3878 required on a per-ruleset basis 3880 o Update description for "location" to be where device intends to 3881 operate, rather than "current location" 3883 o For REGISTRATION_RESP, add clarification that when it is returned, 3884 it will have at least one RulesetInfo. Otherwise, it's an 3885 UNSUPPORTED error. 3887 o Clarified that, when a Master Device asks for spectrum on behalf 3888 of a Slave Device, there are 2 locations in the message and 3889 changed masterDeviceLocation to be required 3891 o Indicate that power levels are typically EIRP (as opposed to 3892 conducted power to the antenna) 3894 o Added description for a "schedule" 3896 o Add intro to DEVICE_VALID_REQ 3897 o TLS: Follow best practices to improve security and interop. 3898 Reference draft-ietf-uta-tls-bcp 3900 o TLS: Use OCSP for better performance; RFC6960 3902 o TLS: When using client auth, Database determines acceptable root 3903 CAs 3905 o Extensibility: Add statement that no extensions that return device 3906 information will not be accepted 3908 o Clarify IANA instructions for the Ruleset ID Registry 3910 o Security: Acknowledge that unauthorized access to device 3911 registration, other sensitive device info is a risk, and indicate 3912 that privacy policies must be published and implement to control 3913 access. 3915 o 3917 Changes from 13: 3919 o Clarification in IANA Section 9 3921 o Use full method name in description of the JSON examples in 3922 Section 6 3924 o Ask RFC Editor to give full iconectiv name in the Addresses 3925 section 3927 o Add URI to ETSC and FCC 3929 Changes from 12: 3931 o Define primitive types in Section 4, specifying UTF-8 for strings 3932 and remove UTF-8 references elsewhere. 3934 o Replace or rephrase "parameter" when reference is to higher-level 3935 structure. 3937 o Replace "MUST" with non-2119 language (maximum length is xxx 3938 octets. 3940 o Rephrase statements that reflected regulatory, not PAWS 3941 requirements (e.g., deletion of "MUST" or "MAY" and rephrasing as 3942 a regulatory requirement). 3944 o Replace "Paws protocol (redundant) to "PAWS" 3945 o Change "geo-location" to "geolocation" 3947 o General references to "Database" changed to "database." 3949 o Simplify Section 6 by showing several JSON encoding examples. 3951 o Change "Device" to "device" 3953 o Moved treatment of List Server as discovery mechanism to 3954 Appendix and added JSON-encoded DB List Server response example. 3956 Changes from 11: 3958 o Change "regulatory rules" to "ruleset" 3960 o Change "regulatory specifics" to "ruleset specifics" 3962 o Change "regulatory-specific" to "ruleset-specific" 3964 o Change "regulatory domain" to "ruleset" where appropriate 3966 o Replace "depends on regulatory domain" to "optional" in tables 3968 o Add "optional" to "*other" in tables 3970 o Change "regulators" to "regulatory domains" 3972 o Change "REQUIRED" error name to "MISSING" 3974 o Changed the IANA instructions and added DE instructions to each 3975 section 3977 o Reformat and reorder IANA sections 3979 Changes from 10: 3981 o Ruleset Name change: ETSI-EN-301-598-1.0.9 and update reference to 3982 PDF 3984 o Add new ETSI parameter: 3985 etsiEnSimultaneousChannelOperationRestriction 3987 o Separate protocol requirements from regulatory requirements 3989 Changes from 09: 3991 o Updated format of the IANA section 3992 Changes from 08: 3994 o Fix JSON typos. 3996 o Added note that JSON schema is not intended to be formally 3997 validated 3999 o Finalize paws-iana-review@ietf.org as the email for updating the 4000 PAWS IANA registries 4002 o URLs to URIs 4004 o Typo fixes 4006 Changes from 07: 4008 o Propose ruleset ID name for ETSI: ETSI-EN-301-598-1.0.0-draft 4010 o Change TBD email address to paws-iana-review@ietf.org for 4011 proposing changes to the PAWS IANA registries 4013 o Moved discussion of required vCard properties to regulatory- 4014 specific sections 4016 o Fixed vCard examples for organization names: Use "fn" property, 4017 but set "kind" to "org". 4019 o Shorten parameter names: 4021 * freqHz -> hz 4023 * powerDbmPerBw -> dbm 4025 Changes from 06: 4027 o Multi-ruleset support: 4029 * Changed RulesetInfo to have single ruleset ID 4031 * Changed INIT_RESP to return a list of RulesetInfo parameters, 4032 rather than a single one 4034 * Changed REGISTRATION_RESP to return a list of RulesetInfo 4035 parameters to indicate the regulatory domains for which 4036 registration was accepted 4038 * Added SpectrumSpec (Section 5.9) parameter to represent 4039 available-spectrum specification for one regulatory domain, 4040 allowing AVAIL_SPECTRUM_RESP and AVAIL_SPECTRUM_BATCH_RESP to 4041 include answers for multiple regulatory domains 4043 * Changed GeoSpectrumSchedule to GeoSpectrumSpec (Section 5.15) 4044 for supporting batch responses to represent available spectrum 4045 for multiple regulatory domains at a location 4047 o To avoid ambiguity or redundant information, clarified that: 4049 * Event-time intervals within a single set of schedules MUST be 4050 disjoint 4052 * A single Spectrum element MUST cover the entire range of 4053 frequencies governed by a ruleset, rather than splitting them 4054 to present a "channelized" view 4056 o Add "ruleset" to Terminology section 4058 o Sync Terminology section with Use Case document 4060 o Add "masterDeviceDesc" to Device Validate request 4062 o Add "masterDeviceLocation" to the AVAIL_SPECTRUM requests and the 4063 SPECTRUM_NOTIFY message. Change "location" to be the location of 4064 the Slave Device, if the request is made by a Master Device on 4065 behalf of a Slave Device 4067 o Update vCard reference and example 4069 o Add jsonrpc 2.0 to all sample messages 4071 o Clarify that Listing Servers may be preconfigured in a device 4073 o Clarify meaning of maximum power levels vs bandwidth, including 4074 renaming parameter names: 4076 o 4078 * maxPowerDBm -> powerDbmPerBw 4080 * bandwidth -> resolutionBwHz 4082 o Explicitly allowed generic JSON-RPC error codes as possible codes. 4084 o Replace SHALL with MUST for consistency 4086 o Replace URI with URL for consistency 4087 o Reduce clutter in JSON encoding examples by removing string- 4088 concatenation characters 4090 o Changed "depends" to "depends on regulatory rules" in several 4091 places 4093 Changes from 05: 4095 o Remove requirement for JSON-RPC 1.0 4097 o More typo fixes and clarifications 4099 Changes from 04: 4101 o Add "masterDeviceDesc" parameter to the available-spectrum 4102 requests to allow both Master and Slave device descriptors when 4103 the Master is making the request on behalf of a Slave. 4105 o Add "requestType" parameter to the available-spectrum requests to 4106 support requesting generic operating parameters for any Slave 4107 Device. 4109 o Add DbUpdateSpec as optional parameter to all response messages 4110 and to the error response to allow a Device to detect a database 4111 change at any stage of the control flow. 4113 o For the OUTSIDE_COVERAGE error, added ability to return a list of 4114 alternate databases 4116 o Explicitly allow JSON-RPC v2.0 and v1.0 encodings 4118 o Relaxed language that state, "MUST stop operation" to "MUST cease 4119 use of spectrum under rules for database-managed spectrum". I.e., 4120 the device may have other fallback strategies allowed by 4121 regulators. 4123 Changes from 03: 4125 o Expanded the Database Discovery mechanism to describe in more 4126 detail pre-configuration with URLs of databases and database- 4127 listing servers, including mechanisms for updating the 4128 configurations when things change 4130 * Add database-change field to Available Spectrum Response 4131 (Section 4.5.2) 4133 o Added fields that are anticipated to be needed by the ETSI 4134 harmonized standard for White Space Devices: 4136 * Added bandwidth constraints to the Available Spectrum Response 4137 (Section 4.5.2) 4139 * Updated Available Spectrum Response to return RulesetInfo, 4140 rather than just a ruleset identifier 4142 * Added optional device-manufacturer and device-model IDs to the 4143 DeviceDescriptor (Section 5.2) message. Also moved fccId from 4144 this message to the IANA section. 4146 * Expanded IANA (Section 9) sections 4148 o Clarified restrictions on the specification of the vertices of a 4149 Polygon. 4151 o Changed default confidence level to 95% for a point with 4152 uncertainty 4154 o Clarified how devices without absolute time source can use the 4155 timestamps in the response messages 4157 o Change method names to start with "spectrum.paws." prefix 4159 o Added maximum string lengths 4161 o Updated author contact info 4163 o More typo fixes 4165 Changes from 02: 4167 o Added timestamp to the AVAIL_SPECTRUM_RESP (Section 4.5.2) and 4168 AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) data models to serve as 4169 a reference for the event times in the response. This was 4170 accidentally omitted (but was specified in their JSON encodings 4171 (Section 6)). 4173 o Fixed typos throughout the JSON encoding (Section 6) sections, 4174 typically adding missing commas. 4176 Changed from 01: 4178 o Added a description of message sequences to support multiple 4179 rulesets and multiple jurisdictions Section 3.1. 4181 o Modified DeviceDescriptor (Section 5.2) to add rulesetIds 4182 parameter 4184 o Modified RulesetInfo (Section 5.6), AvailableSpectrumResponse 4185 (Section 4.5.2) to add rulesetId parameter. 4187 o Add Extensibility (Section 8) section. 4189 o Filled in IANA (Section 9) section. 4191 o Removed blank Example Messages section 4193 Changes from 00: 4195 o Add JSON encoding 4197 o Adopt RFC5491 for GeoLocation 4199 o Adopt vCard for contact information 4201 o Add Response Code section and update text referencing the defined 4202 response codes 4204 o Change DeviceIdentifier to be DeviceDescriptor, allowing 4205 identifiers and device-characteristic fields to be included. 4207 Authors' Addresses 4209 Vincent Chen (editor) 4210 Google 4211 1600 Amphitheatre Parkway 4212 Mountain View, CA 94043 4213 US 4215 Email: vchen@google.com 4217 Subir Das 4218 Applied Communication Sciences 4219 150 Mount Airy Road 4220 Basking Ridge, NJ 07920 4221 U.S.A. 4223 Email: sdas at appcomsci dot com 4225 Lei Zhu 4226 Huawei 4228 Phone: +86 13910157020 4229 Email: lei.zhu@huawei.com 4230 John Malyar 4231 iconectiv 4232 444 Hoes Lane/RRC 4E1106 4233 Piscataway, NJ 08854 4234 U.S.A. 4236 Email: jmalyar at iconectiv dot com 4238 Peter J. McCann 4239 Huawei 4240 400 Crossing Blvd, 2nd Floor 4241 Bridgewater, NJ 08807 4242 USA 4244 Phone: +1 908 541 3563 4245 Email: peter.mccann@huawei.com