PAWS V. Chen, Ed. Internet-Draft Google Intended status: Standards Track S. Das Expires: October 26, 2014 Applied Communication Sciences L. Zhu Huawei J. Malyar iconectiv (formerly Telcordia Interconnection Solutions) P. McCann Huawei April 24, 2014 Protocol to Access White-Space (PAWS) Databases draft-ietf-paws-protocol-12 Abstract Portions of the radio spectrum that are allocated to licensees are available for non-interfering use. This available spectrum is called "White Space." Allowing secondary users access to available spectrum "unlocks" existing spectrum to maximize its utilization and to provide opportunities for innovation, resulting in greater overall spectrum utilization. One approach to manage spectrum sharing uses databases to report spectrum availability to devices. To achieve interoperability among multiple devices and databases, a standardized protocol must be defined and implemented. This document defines such a protocol, the "Protocol to Access White Space (PAWS) Databases". Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 26, 2014. Chen, et al. Expires October 26, 2014 [Page 1] Internet-Draft paws-protocol April 2014 Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 2.1. Conventions Used in This Document . . . . . . . . . . . . 5 2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Multi-ruleset Support . . . . . . . . . . . . . . . . . . 7 4. Protocol Functionalities . . . . . . . . . . . . . . . . . . 8 4.1. Database Discovery . . . . . . . . . . . . . . . . . . . 9 4.1.1. Listing Server . . . . . . . . . . . . . . . . . . . 10 4.2. Initialization . . . . . . . . . . . . . . . . . . . . . 10 4.2.1. INIT_REQ . . . . . . . . . . . . . . . . . . . . . . 11 4.2.2. INIT_RESP . . . . . . . . . . . . . . . . . . . . . . 12 4.3. Device Registration . . . . . . . . . . . . . . . . . . . 12 4.3.1. REGISTRATION_REQ . . . . . . . . . . . . . . . . . . 13 4.3.2. REGISTRATION_RESP . . . . . . . . . . . . . . . . . . 14 4.4. Available Spectrum Query . . . . . . . . . . . . . . . . 15 4.4.1. AVAIL_SPECTRUM_REQ . . . . . . . . . . . . . . . . . 17 4.4.2. AVAIL_SPECTRUM_RESP . . . . . . . . . . . . . . . . . 19 4.4.3. AVAIL_SPECTRUM_BATCH_REQ . . . . . . . . . . . . . . 21 4.4.4. AVAIL_SPECTRUM_BATCH_RESP . . . . . . . . . . . . . . 23 4.4.5. SPECTRUM_USE_NOTIFY . . . . . . . . . . . . . . . . . 25 4.4.6. SPECTRUM_USE_RESP . . . . . . . . . . . . . . . . . . 26 4.5. Device Validation . . . . . . . . . . . . . . . . . . . . 26 4.5.1. DEV_VALID_REQ . . . . . . . . . . . . . . . . . . . . 28 4.5.2. DEV_VALID_RESP . . . . . . . . . . . . . . . . . . . 28 5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 29 5.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . . . 29 5.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . . 31 5.3. AntennaCharacteristics . . . . . . . . . . . . . . . . . 32 5.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . . 33 Chen, et al. Expires October 26, 2014 [Page 2] Internet-Draft paws-protocol April 2014 5.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . . . 34 5.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . . . 34 5.7. DbUpdateSpec . . . . . . . . . . . . . . . . . . . . . . 35 5.8. DatabaseSpec . . . . . . . . . . . . . . . . . . . . . . 36 5.9. SpectrumSpec . . . . . . . . . . . . . . . . . . . . . . 36 5.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . . 38 5.11. Spectrum . . . . . . . . . . . . . . . . . . . . . . . . 39 5.12. SpectrumProfile . . . . . . . . . . . . . . . . . . . . . 42 5.13. FrequencyRange . . . . . . . . . . . . . . . . . . . . . 43 5.14. EventTime . . . . . . . . . . . . . . . . . . . . . . . . 43 5.15. GeoSpectrumSpec . . . . . . . . . . . . . . . . . . . . . 44 5.16. DeviceValidity . . . . . . . . . . . . . . . . . . . . . 45 5.17. Error Element . . . . . . . . . . . . . . . . . . . . . . 45 5.17.1. OUTSIDE_COVERAGE Error . . . . . . . . . . . . . . . 47 5.17.2. DATABASE_CHANGE Error . . . . . . . . . . . . . . . . 48 5.17.3. MISSING Error . . . . . . . . . . . . . . . . . . . . 48 6. Message Encoding . . . . . . . . . . . . . . . . . . . . . . 49 6.1. JSON-RPC Binding . . . . . . . . . . . . . . . . . . . . 49 6.2. init Method . . . . . . . . . . . . . . . . . . . . . . . 50 6.2.1. INIT_REQ Parameters . . . . . . . . . . . . . . . . . 51 6.2.2. INIT_RESP Parameters . . . . . . . . . . . . . . . . 52 6.3. register Method . . . . . . . . . . . . . . . . . . . . . 54 6.3.1. REGISTRATION_REQ Parameters . . . . . . . . . . . . . 54 6.3.2. REGISTRATION_RESP Parameters . . . . . . . . . . . . 55 6.4. getSpectrum Method . . . . . . . . . . . . . . . . . . . 56 6.4.1. AVAIL_SPECTRUM_REQ Parameters . . . . . . . . . . . . 57 6.4.2. AVAIL_SPECTRUM_RESP Parameters . . . . . . . . . . . 59 6.5. getSpectrumBatch Method . . . . . . . . . . . . . . . . . 63 6.5.1. AVAIL_SPECTRUM_BATCH_REQ Parameters . . . . . . . . . 64 6.5.2. AVAIL_SPECTRUM_BATCH_RESP Parameters . . . . . . . . 66 6.6. notifySpectrumUse Method . . . . . . . . . . . . . . . . 69 6.6.1. SPECTRUM_USE_NOTIFY Parameters . . . . . . . . . . . 69 6.6.2. SPECTRUM_USE_RESP Parameters . . . . . . . . . . . . 71 6.7. verifyDevice Method . . . . . . . . . . . . . . . . . . . 72 6.7.1. DEV_VALID_REQ Parameters . . . . . . . . . . . . . . 72 6.7.2. DEV_VALID_RESP Parameters . . . . . . . . . . . . . . 73 6.8. Sub-message Schemas . . . . . . . . . . . . . . . . . . . 75 6.8.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . 75 6.8.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . 77 6.8.3. AntennaCharacteristics . . . . . . . . . . . . . . . 78 6.8.4. DeviceCapabilities . . . . . . . . . . . . . . . . . 79 6.8.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . 80 6.8.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . 81 6.8.7. DbUpdateSpec . . . . . . . . . . . . . . . . . . . . 82 6.8.8. DatabaseSpec . . . . . . . . . . . . . . . . . . . . 83 6.8.9. Spectrum . . . . . . . . . . . . . . . . . . . . . . 83 6.8.10. FrequencyRange . . . . . . . . . . . . . . . . . . . 85 6.8.11. EventTime . . . . . . . . . . . . . . . . . . . . . . 86 Chen, et al. Expires October 26, 2014 [Page 3] Internet-Draft paws-protocol April 2014 6.8.12. SpectrumSchedule . . . . . . . . . . . . . . . . . . 86 6.8.13. SpectrumSpec . . . . . . . . . . . . . . . . . . . . 87 6.8.14. GeoSpectrumSpec . . . . . . . . . . . . . . . . . . . 88 6.8.15. DeviceValidity . . . . . . . . . . . . . . . . . . . 89 6.8.16. Additional Properties . . . . . . . . . . . . . . . . 90 7. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . . . 90 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 92 8.1. Defining Ruleset Identifiers . . . . . . . . . . . . . . 92 8.2. Defining New Message Parameters . . . . . . . . . . . . . 92 8.3. Defining Additional Error Codes . . . . . . . . . . . . . 93 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 93 9.1. PAWS Ruleset ID Registry . . . . . . . . . . . . . . . . 94 9.1.1. Registration Template . . . . . . . . . . . . . . . . 94 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 94 9.2. PAWS Parameters Registry . . . . . . . . . . . . . . . . 100 9.2.1. Registration Template . . . . . . . . . . . . . . . . 100 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 100 9.3. PAWS Error Code Registry . . . . . . . . . . . . . . . . 102 9.3.1. Registration Template . . . . . . . . . . . . . . . . 102 9.3.2. Initial Registry Contents . . . . . . . . . . . . . . 103 10. Security Considerations . . . . . . . . . . . . . . . . . . . 103 10.1. Assurance of Proper Database . . . . . . . . . . . . . . 104 10.2. Protection Against Modification . . . . . . . . . . . . . 104 10.3. Protection Against Eavesdropping . . . . . . . . . . . . 104 10.4. Client Authentication Considerations . . . . . . . . . . 105 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 105 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 106 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 106 13.1. Normative References . . . . . . . . . . . . . . . . . . 106 13.2. Informative References . . . . . . . . . . . . . . . . . 107 Appendix A. Changes / Author Notes. . . . . . . . . . . . . . . 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 112 Chen, et al. Expires October 26, 2014 [Page 4] Internet-Draft paws-protocol April 2014 1. Introduction This section provides some high level introductory material. Readers are strongly encouraged to read Protocol to Access White-Space (PAWS) Databases: Use Cases and Requirements [RFC6953] for use cases, requirements, and additional background. A geospatial database can track available spectrum (in accordance with the rules of one or more regulatory domains) and make this information available to devices. This approach shifts the complexity of spectrum-policy conformance out of the device and into the Database. This approach also simplifies adoption of policy changes, limiting updates to a handful of databases, rather than numerous devices. It opens the door for innovations in spectrum management that can incorporate a variety of parameters, including user location and time. In the future, it also can include other parameters, such as user priority, time, signal type and power, spectrum supply and demand, payment or micro-auction bidding, and more. In providing this service, a database records and updates information necessary to protect primary users -- for example, this information may include parameters such as a fixed transmitter's call sign, its geo-location, antenna height, power, and periods of operation. The rules that the Database must follow, including its schedule for obtaining and updating protection information, protection rules, and information reported to devices, vary according to regulatory domain. Such variations, however, should be handled by each database, and exposure to the variations by devices should be minimized. This specification defines an extensible protocol to obtain available spectrum from a geospatial database by a device with geo-location capability. It enables a device to operate in any regulatory domain that implements the same protocol and in which the device is authorized to operate. The document describes the use of HTTP/TLS as transport for the protocol. 2. Conventions and Terminology 2.1. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels [RFC2119]. Chen, et al. Expires October 26, 2014 [Page 5] Internet-Draft paws-protocol April 2014 2.2. Terminology Database or Spectrum Database: A database is an entity that contains current information about available spectrum at a given location and time, as well as other types of information related to spectrum availability and usage. Device ID An identifier for a device. EIRP: Effective isotropically radiated power ETSI: European Telecommunications Standards Institute FCC: Federal Communications Commission Listing server: A server that provides the URIs for one or more Spectrum Databases. A regulator, for example, may operate a Database Listing Server to publish the list of authorized Spectrum Databases for its regulatory domain. Master Device: A device that queries the database, on its own behalf and/or on behalf of a slave device, to obtain available spectrum information. Regulatory Domain: A location where certain rules apply to the use of white space spectrum, including the operation of databases and devices involved in its use. A regulatory domain is normally defined by a unit of government for a particular country, but the PAWS protocol is agnostic as to how a regulatory domain is constructed. Ruleset: An IANA-registered set of rules that governs operations of white space devices and Spectrum Databases. A regulatory authority can define and register its own rulesets, or can use rulesets that have been previously registered by others. Slave Device: A device that queries the database through a master device. 3. Protocol Overview A Master Device uses the PAWS protocol to obtain a schedule of available spectrum at its location. The security necessary to ensure the accuracy, privacy, and confidentiality of the Device's location is described in the Security Considerations (Section 10). This document assumes that the Master Device and the Database are connected to the Internet. A typical sequence of PAWS operations is outlined as follows. See Protocol Functionalities (Section 4) and Protocol Parameters (Section 5) for details: 1. The Master Device obtains (statically or dynamically) the URI for a Database appropriate for its location to send subsequent PAWS messages. Chen, et al. Expires October 26, 2014 [Page 6] Internet-Draft paws-protocol April 2014 2. The Master Device establishes an HTTPS session with the Database. 3. The Master Device optionally sends an initialization message to the Database to exchange capabilities. 4. If the Database receives an initialization message, it responds with a message in the body of the HTTP response. 5. The Database may require the Master Device to be registered before providing service. 6. The Master Device sends an available-spectrum request message to the Database. 7. The Master Device may verify with the Database that the Slave Device is valid. 8. The Database responds with an available-spectrum response message in the body of the HTTP response. 9. The Master Device may send a spectrum-usage notification message to the Database. 10. If the Database receives a spectrum-usage notification message, it responds by sending the Master Device a spectrum-usage acknowledgement message. Different regulatory domains may impose particular requirements, such as requiring Master Devices to register with the Database, performing Slave Device verification, and sending spectrum usage notifications. 3.1. Multi-ruleset Support For a Master Device that supports multiple rulesets and operates with multiple databases, the PAWS protocol supports the following sequence of operations for each request by the Master Device: 1. The Master Device includes in its request its location and optionally includes the identifier of all the rulesets it supports and any parameter values it might need for the request 2. The Database uses the device location and also may use the ruleset list to determine its response, for example, to select the list of required parameters 3. If required parameters are missing from the request, the Database responds with an error and a list of names of the missing parameters 4. The Master Device makes the request again, adding the missing parameter values 5. The Database responds to the request, including the identifier of the applicable ruleset 6. The Master Device uses the indicated ruleset to determine how to interpret the Database response NOTE: Regulatory rules contain many device-only requirements that govern device behavior, independent of any database rules. These Chen, et al. Expires October 26, 2014 [Page 7] Internet-Draft paws-protocol April 2014 requirements may be complex and involve device behavior that are not easily parameterized. The ruleset-id parameter provides a mechanism for the Database to inform the Master Device of the applicable ruleset without having to express device-side behavior within the protocol. The ruleset identifier is a string value that contains the name of the regulatory body that established the rules and version information, such as "FccTvBandWhiteSpace-2010". By separating the regulatory "authority" from the "ruleset-id", it allows the protocol to support multiple regulatory authorities that use the same device-side ruleset. It also allows support for a single authority to define multiple rulesets. 4. Protocol Functionalities The PAWS protocol consists of several components: o Database Discovery (Section 4.1) MUST be supported by the Master Device o Initialization (Section 4.2) MAY be used by the Master Device and MUST be implemented by the Database. o Device Registration (Section 4.3) MAY be used by the Master Device and MAY be implemented by the Database, either as a separate component or as part of the Available Spectrum Query (Section 4.4) component. o Available Spectrum Query (Section 4.4) MUST be supported by Master Device and the Database. o Spectrum Use Notify (Section 4.4.5) MAY be used by the Master Device and the Database. o Device Validation (Section 4.5) MAY be used by the Master Device and the Database. Note: Some regulatory domains mandate the use of notification and device validation. In such cases, obviously, their implementation and use would be necessary. This section describes the protocol components and their messages. Protocol Parameters (Section 5) contains a more thorough discussion of the parameters that comprise the PAWS request and response messages. Message Encoding (Section 6) provides details of the message encodings. HTTPS Binding (Section 7) describes the use of HTTPS (HTTP Over TLS [RFC2818]) for transporting PAWS messages and optional device authentication. The parameter tables in this section and Protocol Parameters (Section 5) are for reference and contain the name of each parameter, the data type of each parameter, and whether the existence of the Chen, et al. Expires October 26, 2014 [Page 8] Internet-Draft paws-protocol April 2014 parameter is required for the protocol transaction in question. The data types are either defined in Protocol Parameters (Section 5) or are part of the base data types specified in The JavaScript Object Notation (JSON) Data Interchange Format [RFC7159]. See Protocol Parameters (Section 5) and Message Encoding (Section 6) for more detail on data types and encodings. 4.1. Database Discovery Preconfiguration The Master Device can be provisioned statically with the URI of one or more Databases. For example, in a particular regulatory domain, there may be a number of certified databases that any device operating in that domain is permitted to connect to, and those URIs can be provisioned in the device. Alternatively, a Master Device can be provisioned statically with the URI of a Database Listing Server, from which it can retrieve URIs of available Databases. Configuration Update To adapt to changes in the list of certified or approved databases, the Device needs to update its preconfigured list of databases. If the Master Device retrieves its preconfigured list of databases from a listing server, the device SHOULD check the listing server periodically to update its list. A Database MAY indicate that its URI will be changing by including the URI of one or more alternate databases (See DbUpdateSpec (Section 5.7)) in its responses to a Device. Before a Database ceases operation, for example, it MUST include DbUpdateSpec in its responses to notify Devices. A Device will update its preconfigured list of databases to replace (only) its entry for the responding Database with the URIs of the alternate databases; the list of alternate databases does not affect any other entries. Error Handling The Device SHOULD select another database from its list of preconfigured databases if: o The selected database is unreachable or does not respond. o The selected database returns an UNSUPPORTED error (see Error Codes (Section 5.17)), which may indicate that the database does not support the regulatory domain where the device is located. If a suitable database cannot be contacted, the Device MUST treat this as equivalent to a response indicating no available spectrum. Chen, et al. Expires October 26, 2014 [Page 9] Internet-Draft paws-protocol April 2014 If the Device is already operating when it fails to contact a suitable database, the spectrum the Device is currently using can be used for as long as the spectrum data is valid, but after that period of time, the Device will no longer have valid spectrum to use. Some regulatory domains will have specific rules regarding how long the spectrum data remains valid in these cases. 4.1.1. Listing Server The use of a Database Listing Server allows the Device to determine the URIs of available databases. When a Listing Server is used, the Device can save the database list and SHOULD contact the Database Listing Server periodically to update its list. The time between such updates MUST be no longer than one week, although the update interval can be shorter (for example, when required by the applicable regulatory domain). If the Device is unable to contact the Database Listing Server to obtain the list of databases for the domain, the Device MUST treat this as equivalent to not having available spectrum. The Database Listing request procedure is depicted in Figure 1. o LISTING_REQ is the database-listing request message o LISTING_RESP is the database-listing response message +---------------+ +-------------------+ | Master Device | | Listing Server | +---------------+ +-------------------+ | | | LISTING_REQ | |-------------------->| | | | LISTING_RESP | |<--------------------| | | Figure 1 TBD Define message format 4.2. Initialization A Master Device SHOULD use the initialization procedure to exchange capability information with the Database whenever the Master Device powers up or initiates communication with the Database. The initialization response informs the Master Device of specific parameterized-rule values, such as threshold distances and time Chen, et al. Expires October 26, 2014 [Page 10] Internet-Draft paws-protocol April 2014 periods beyond which the Device must update its available-spectrum data (see RuleSetInfo (Section 5.6)). When a Master Device is configured manually with these parameterized-rule values, it does not need to use the initialization procedure. The initialization message also represents extension points for database implementations or rulesets that require the extra handshake. The Initialization request procedure is depicted in Figure 2. o INIT_REQ (Section 4.2.1) is the initialization request message o INIT_RESP (Section 4.2.2) is the initialization response message +---------------+ +-------------------+ | Master Device | | Spectrum Database | +---------------+ +-------------------+ | | | INIT_REQ | |-------------------->| | | | INIT_RESP | |<--------------------| | | Figure 2 4.2.1. INIT_REQ The initialization request message allows the Master Device to initiate exchange of capabilities with the Database. +---------------------------------------+ |INIT_REQ | +----------------------------+----------| |deviceDesc:DeviceDescriptor | required | |location:GeoLocation | required | |.......................................| |*other:any | optional | +----------------------------+----------+ Parameters: deviceDesc: The DeviceDescriptor (Section 5.2) for the Device is REQUIRED. If the Database does not support the device or any of the rulesets specified in the device descriptor, it MUST return an error with the UNSUPPORTED (Table 1) code in the error response. If the device descriptor does not contain any ruleset IDs, the Database SHOULD return a list of RulesetInfo (Section 5.6) parameters for each ruleset it supports at the specified location. Chen, et al. Expires October 26, 2014 [Page 11] Internet-Draft paws-protocol April 2014 location: The GeoLocation (Section 5.1) for the Device is REQUIRED. other: The Master Device MAY specify additional handshake parameters in the INIT_REQ message. The Database MUST ignore all parameters it does not understand. To simplify its initialization logic, a Master Device that supports multiple Databases and rulesets can include the union of all required parameters for all its supported rulesets. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.2.2. INIT_RESP The initialization response message communicates database parameters to the requesting device. +---------------------------------------+ |INIT_RESP | +----------------------------+----------+ 1..* +-------------+ |rulesetInfos:list | required |------->| RulesetInfo | |databaseChange:DbUpdateSpec | optional | +-------------+ |.......................................| |*other:any | optional | +----------------------------+----------+ Parameters: rulesetInfos: A list of RulesetInfo (Section 5.6) parameters MUST be included in the response. Each RulesetInfo parameter corresponds to a ruleset supported by the Database and is applicable to the location specified in the INIT_REQ (Section 4.2.1) message. If the Device included a list of ruleset IDs in the DeviceDescriptor parameter of its INIT_REQ message, each RulesetInfo parameter in the response MUST match one of the specified ruleset IDs. databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) parameter to notify the Master Device of a change to the Database URI, providing one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding database with the list of alternate URIs. other: The Database MAY include additional handshake parameters in the INIT_RESP (Section 4.2.2) message. The Master Device MUST ignore all parameters it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.3. Device Registration Some rulesets require a Master Device to send its registration information to the Database in order to establish certain operational Chen, et al. Expires October 26, 2014 [Page 12] Internet-Draft paws-protocol April 2014 parameters. FCC rules, for example, require that a 'Fixed Device' register its owner and operator contact information, its device identifier, its location, and its antenna height. The Database MAY support device registration as a separate Device Registration component, or as part of the Spectrum Availability component. If the Database does not support a separate Device Registration request, it MUST return an error with the UNIMPLEMENTED (Table 1) code in the error-response message. The Device Registration request procedure is depicted in Figure 3. o REGISTRATION_REQ (Section 4.3.1) is the device-registration request message o REGISTRATION_RESP (Section 4.3.2) is the device-registration response message +---------------+ +-------------------+ | Master Device | | Spectrum Database | +---------------+ +-------------------+ | | | REGISTRATION_REQ | |------------------------>| | | | REGISTRATION_RESP | |<------------------------| | | Figure 3 4.3.1. REGISTRATION_REQ The registration request message contains the required registration parameters. A parameter marked as optional may be required by some rulesets. +-------------------------------------------+ |REGISTRATION_REQ | +-------------------------------+-----------+ |deviceDesc:DeviceDescriptor | required | |location:GeoLocation | required | |deviceOwner:DeviceOwner | required | |antenna:AntennaCharacteristics | optional | |...........................................| |*other:any | optional | +-------------------------------+-----------+ Parameters: Chen, et al. Expires October 26, 2014 [Page 13] Internet-Draft paws-protocol April 2014 deviceDesc: The DeviceDescriptor (Section 5.2) for the Master Device is REQUIRED. The ruleset IDs included in this parameter value indicate the rulesets for which the Device wishes to register. If the registration information is unacceptable for all of the rulesets supported by the Database, the Database MUST return an error message with an appropriate error code. Otherwise, the Database MUST return, in its response, a list of RulesetInfo (Section 5.6) parameters for all rulesets for which device registration was accepted. location: The GeoLocation (Section 5.1) for the Device is REQUIRED. deviceOwner: The DeviceOwner (Section 5.5) information is REQUIRED. antenna: The AntennaCharacteristics (Section 5.3) is OPTIONAL. other: Rulesets and database implementations may require additional registration parameters. To simplify its registration logic, the Master Device MAY send a union of the registration information required by all supported rulesets. The Database MUST ignore all parameters it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.3.2. REGISTRATION_RESP The registration response message acknowledges successful registration by including a RulesetInfo message for each ruleset in which the registration is accepted. If the Database accepts the registration for none of the rulesets it supports, the Database MUST return the NOT_REGISTERED error (See Error Codes (Section 5.17)). +---------------------------------------+ |REGISTRATION_RESP | +----------------------------+----------+ 1..* +-------------+ |rulesetInfos:list | required |------->| RulesetInfo | |databaseChange:DbUpdateSpec | optional | +-------------+ |............................|..........| |*other:any | optional | +----------------------------+----------+ Parameters: rulesetInfos: A list of RulesetInfo (Section 5.6) parameters MUST be included in the response. Each entry corresponds to a ruleset for which the registration was accepted. The list MUST contain at least one entry. databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) parameter to notify the Master Device of a change to the Database URI, providing one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding database with the list of alternate URIs. Chen, et al. Expires October 26, 2014 [Page 14] Internet-Draft paws-protocol April 2014 other: Database implementations MAY return additional parameters in the registration response. The Master Device MUST ignore any parameters it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.4. Available Spectrum Query To obtain the available spectrum from the Database, a Master Device sends a request that contains its geo-location and any parameters required by the ruleset (such as device identifier, capabilities, and characteristics). The Database returns a response that describes which frequencies are available, at what permissible operating power levels, and a schedule of when they are available. The Available Spectrum Query procedure is depicted in Figure 4. o AVAIL_SPECTRUM_REQ (Section 4.4.1) is the available-spectrum request message. o AVAIL_SPECTRUM_RESP (Section 4.4.2) is the available-spectrum response message. o AVAIL_SPECTRUM_BATCH_REQ (Section 4.4.3) is an OPTIONAL batch version of the available-spectrum request message that allows multiple locations to be specified in the request. o AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) is the response message for the batch version of the available-spectrum request that contains available spectrum for each location in the request. o SPECTRUM_USE_NOTIFY (Section 4.4.5) is the spectrum-usage notification message. o SPECTRUM_USE_RESP (Section 4.4.6) is the spectrum-usage acknowledgment message. Chen, et al. Expires October 26, 2014 [Page 15] Internet-Draft paws-protocol April 2014 +---------------+ +-------------------+ | Master Device | | Spectrum Database | +---------------+ +-------------------+ | | | AVAIL_SPECTRUM_REQ | | (AVAIL_SPECTRUM_BATCH_REQ) | |--------------------------->| | | | AVAIL_SPECTRUM_RESP | | (AVAIL_SPECTRUM_BATCH_RESP)| |<---------------------------| | | | (SPECTRUM_USE_NOTIFY) | |--------------------------->| | | | (SPECTRUM_USE_RESP) | |<---------------------------| | | Figure 4 1. First, the Master Device sends an available-spectrum request message to the Database. 2. The Database MUST respond with an error using the NOT_REGISTERED (Table 1) code if: * registration information is required, and * the request does not include registration information, and * the Device has not previously registered with the Database 3. If the location specified in the request is outside the regulatory domain supported by the Database, the Database MUST respond with an OUTSIDE_COVERAGE (Table 1) error. If some locations within a batch request are outside the regulatory domain supported by the Database, the Database MAY return an OK response with available spectrum for only the valid locations; otherwise, if all locations within a batch request are outside the regulatory domain, the Database MUST respond with an OUTSIDE_COVERAGE error. 4. The Database MAY perform other validation of the request, (e.g., checking for missing required parameters, authorizations). If validation fails, the Database returns an appropriate error code (Table 1). If the request is missing required parameters, the Database MUST respond with a MISSING (Table 1) error and SHOULD include a list of the missing parameters. 5. If the request is valid, the Database responds with an available- spectrum response message. If the ruleset requires that devices must report anticipated spectrum usage, the Database will indicate so in the response message. Chen, et al. Expires October 26, 2014 [Page 16] Internet-Draft paws-protocol April 2014 6. If the available-spectrum response indicates that the Master Device must send a spectrum-usage notification message, the Master Device sends the notification message to the Database. 7. If the Database receives a spectrum-usage notification message, it MUST send a spectrum-usage acknowledgment message to the Master Device. The procedure for asking for available spectrum on behalf of a Slave Device is similar, except that the process is initiated by the Slave Device. The device identifier, capabilities, and characteristics communicated in the AVAIL_SPECTRUM_REQ message MUST be those of the Slave Device, but the location MUST be that of the Master Device. Although the communication and protocol between the Slave Device and Master Device is outside the scope of this document (represented as dotted lines), the expected message sequence is shown in Figure 5. +------------+ +---------------+ +-------------------+ |Slave Device| | Master Device | | Spectrum Database | +------------+ +---------------+ +-------------------+ | | | | AVAIL_SPEC_REQ | | |................>| | | | | | | AVAIL_SPECTRUM_REQ | | |-------------------------->| | | | | | AVAIL_SPECTRUM_RESP | | |<--------------------------| | AVAIL_SPEC_RESP | | |<................| | | | | | (SPECTRUM_USE) | | |................>| (SPECTRUM_USE_NOTIFY) | | |-------------------------->| | | | | | (SPECTRUM_USE_RESP) | | |<--------------------------| | | | Figure 5 4.4.1. AVAIL_SPECTRUM_REQ The request message for the Available Spectrum Query protocol MUST include a geo-location. Rulesets may mandate that it be the Device's current location or allow it to be an anticipated location. A parameter marked as optional may be required by some rulesets. Chen, et al. Expires October 26, 2014 [Page 17] Internet-Draft paws-protocol April 2014 +----------------------------------------------------+ |AVAIL_SPECTRUM_REQ | +----------------------------------+-----------------+ |deviceDesc:DeviceDescriptor | see description | |location:GeoLocation | see description | |owner:DeviceOwner | optional | |antenna:AntennaCharacteristics | optional | |capabilities:DeviceCapabilities | optional | |masterDeviceDesc:DeviceDescriptor | optional | |masterDeviceLocation:GeoLocation | optional | |requestType:string | optional | |..................................|.................| |*other:any | optional | +----------------------------------+-----------------+ Parameters: deviceDesc: The DeviceDescriptor (Section 5.2) for the Device requesting available spectrum. When the request is made by a Master Device on its own behalf, the descriptor is that of the Master Device and it is REQUIRED. When the request is made on behalf of a Slave Device, the descriptor is that of the Slave Device, and it is REQUIRED if the "requestType" parameter is not specified. The deviceDesc parameter may be OPTIONAL for some values of requestType. location: The GeoLocation (Section 5.1) for the Device requesting available spectrum. The location SHOULD be the current location of the Device, but more precisely, the location of the radiation center of the Device's antenna. When the request is made by the Master Device on its own behalf, the location is that of the Master Device and it is REQUIRED. When the request is made by the Master Device on behalf of a Slave Device, the location is that of the Slave Device and it is OPTIONAL (see also the masterDeviceLocation parameter). The location may be an anticipated position of the Device to support mobile devices, but its use depends on the ruleset. If the location specifies a region, rather than a point, the Database MAY return an error with the UNIMPLEMENTED (Table 1) code, if it does not support query by region. owner: The DeviceOwner (Section 5.5) information MAY be included to register the Device with the Database. This enables the Device to register and get spectrum-availability information in a single request. Some rulesets mandate registration for specific device types. Chen, et al. Expires October 26, 2014 [Page 18] Internet-Draft paws-protocol April 2014 antenna: The AntennaCharacteristics (Section 5.3) is OPTIONAL. capabilities: The Master Device MAY include its DeviceCapabilities (Section 5.4) to limit the available-spectrum response to the spectrum that is compatible with its capabilities. The Database SHOULD NOT return spectrum that is not compatible with the specified capabilities. masterDeviceDesc: When the request is made by the Master Device on behalf of a Slave Device, the Master Device MAY provide its own descriptor. masterDeviceLocation: When the request is made by the Master Device on behalf of a Slave Device, the Master Device MAY provide its own GeoLocation (Section 5.1). requestType: The request type is an OPTIONAL parameter that may be used to modify the request, but its use depends on the applicable ruleset. The request type may be used, for example, to indicate a the response should include generic Slave Device parameters without having to specify the device descriptor for a specific device. When the requestType parameter is missing, the request is for a specific device (Master or Slave), so the deviceDesc parameter is REQUIRED. The length of the value MUST NOT exceed 64 octets. See IANA Ruleset Registry, Initial Registry Contents (Section 9.1.2) for ruleset specifics. other: Rulesets and database implementations may require additional request parameters. The Database MUST ignore all parameters it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.4.2. AVAIL_SPECTRUM_RESP The response message for the Available Spectrum Query contains one or more SpectrumSpec (Section 5.9) elements, one for each ruleset supported at the location specified in the corresponding AVAIL_SPECTRUM_REQ (Section 4.4.1) request. Each SpectrumSpec element contains a list of one or more spectrum schedules, representing permissible power levels over time: o Within each list of schedules, event-time intervals MUST be disjoint and MUST be sorted in increasing time. o A gap in the time schedule means no spectrum is available for that time interval. Chen, et al. Expires October 26, 2014 [Page 19] Internet-Draft paws-protocol April 2014 +---------------------------------------+ |AVAIL_SPECTRUM_RESP | +----------------------------+----------+ |timestamp:string | required | |deviceDesc:DeviceDescriptor | required | |spectrumSpecs:list | required |-------+ |............................|..........| | |databaseChange:DbUpdateSpec | optional | | |*other:any | optional | | +----------------------------+----------+ | 1..* V +-----------------------------------+ |SpectrumSpec | +------------------------+----------+ |rulesetInfo:RulesetInfo | required | |spectrumSchedules:list | required |-+ |timeRange:EventTime | optional | | |frequencyRanges:list | optional | | |needsSpectrumReport:bool| optional | | |maxTotalBwHz:float | optional | | |maxContiguousBwHz:float | optional | | +------------------------+----------+ | +--------------------+ | 1..* V +-------------------------------+ |SpectrumSchedule | +--------------------+----------+ |eventTime:EventTime | required | |spectra:list | required | +--------------------+----------+ Parameters: timestamp: Timestamp of the response of the form, YYYY-MM- DDThh:mm:ssZ, as defined by Date and Time on the Internet: Timestamps [RFC3339]. This can be used by the Device as a reference for the start and stop times in the spectrum schedules. deviceDesc: The Database MUST include the DeviceDescriptor (Section 5.2) specified in the AVAIL_SPECTRUM_REQ message. spectrumSpecs: The SpectrumSpec (Section 5.9) list MUST include at least one entry. Each entry contains the schedules of available spectrum for a ruleset. The Database MAY return more than one SpectrumSpec to represent available spectrum for multiple rulesets at the specified location. Chen, et al. Expires October 26, 2014 [Page 20] Internet-Draft paws-protocol April 2014 databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) parameter to notify the Device of a change to the Database URI, providing one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding database with the list of alternate URIs. other: Database implementations MAY return additional parameters in the response. The Device MUST ignore any parameters that it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters and requirements they place on the Device. 4.4.2.1. Update Requirements When the stop time specified in the schedule has been reached, the Device: o MUST obtain a new spectrum-availability schedule, either by using the next one in the list (if provided) or making another Available Spectrum Query (Section 4.4). o If the Device is unable to contact the Database to obtain a new schedule, it MUST treat this as equivalent to a response with no available spectrum. Some rulesets also mandate that a Device must obtain a new specturm- availability schedule if the Device moves beyond a threshold distance (established by the ruleset) away from the actual location and all anticipated location(s) it reported in previous AVAIL_SPECTRUM_REQ or AVAIL_SPECTRUM_BATCH_REQ requests (see "maxLocationChange" in RulesetInfo (Section 5.6)). If the Device is unable to contact the Database to obtain a new schedule, it MUST treat this as equivalent to a response with no available spectrum. NOTE: The ruleset determines required device behavior when spectrum is no longer available. The ruleset also governs whether a device may request and use spectrum at anticipated locations beyond the threshold distance from its current location. 4.4.3. AVAIL_SPECTRUM_BATCH_REQ The Database MAY support the batch request that allows multiple locations to be specified. This enables a portable Master Device, for example, to get available spectrum for a sequence of anticipated locations using a single request. The Database interprets each location in the batch request as if it were an independent request and returns results consistent with multiple individual AVAIL_SPECTRUM_REQ (Section 4.4.1) requests, but returns these results in a batched response (Section 4.4.4). The request message for the batch Available Spectrum Query protocol MUST include at least Chen, et al. Expires October 26, 2014 [Page 21] Internet-Draft paws-protocol April 2014 one GeoLocation (Section 5.1). If the Database does not support batch requests, it MUST return an UNIMPLEMENTED (Table 1) error. NOTE: Whether anticipated locations are allowed depends on the specified ruleset. A parameter marked as optional may be required by some rulesets. +---------------------------------------------------+ |AVAIL_SPECTRUM_BATCH_REQ | +---------------------------------+-----------------+ |deviceDesc:DeviceDescriptor | see description | |locations:list | required |--+ |owner:DeviceOwner | optional | | |antenna:AntennaCharacteristics | optional | | |capabilities:DeviceCapabilities | optional | | |masterDeviceDesc:DeviceDescriptor| optional | | |masterDeviceLocation:GeoLocation | optional | | |requestType:string | optional | | +.................................+.................+ | |*other:any | optional | | +---------------------------------+-----------------+ | | 1..* V +-------------+ | GeoLocation | +-------------+ Parameters: deviceDesc: The DeviceDescriptor (Section 5.2) for the Device requesting available spectrum. When the request is made by a Master Device on its own behalf, the descriptor is that of the Master Device and it is REQUIRED. When the request is made on behalf of a Slave Device, the descriptor is that of the Slave Device, and it is REQUIRED if the "requestType" parameter is not specified. The deviceDesc parameter may be OPTIONAL for some values of requestType. locations: The GeoLocation (Section 5.1) list for the Device is REQUIRED. This allows the Device to specify its actual location plus additional anticipated locations. At least one location MUST be included. This specification places no upper limit on the number of locations, but the Database MAY restrict the number of locations it supports by returning a response with fewer locations than specified in the request. If the locations specify regions, rather than points, the Database MAY return an error with the UNIMPLEMENTED (Table 1) code, if it does not support query by region. When the request is made by a Master Device on its own behalf, the locations are those of the Master Device. When the Chen, et al. Expires October 26, 2014 [Page 22] Internet-Draft paws-protocol April 2014 request is made by the Master Device on behalf of a Slave Device, the locations are those of the Slave Device (see also the masterDeviceLocation parameter). owner: The DeviceOwner (Section 5.5) information MAY be included to register the Device with the Database. This enables the Device to register and get spectrum-availability information in a single request. Some rulesets mandate registration for specific device types. antenna: The AntennaCharacteristics (Section 5.3) is OPTIONAL. capabilities: The Master Device MAY include its DeviceCapabilities (Section 5.4) to limit the available-spectrum response to the spectrum that is compatible with its capabilities. The Database SHOULD NOT return spectrum that is not compatible with the specified capabilities. masterDeviceDesc: When the request is made by the Master Device on behalf of a Slave Device, the Master Device MAY provide its own descriptor. masterDeviceLocation: When the request is made by the Master Device on behalf of a Slave Device, the Master Device MAY provide its own GeoLocation (Section 5.1). requestType: The request type is an OPTIONAL parameter that may be used to modify the request, but its use depends on applicable the ruleset. The request type may be used, for example, to request generic Slave Device parameters without having to specify the device descriptor for a specific device. When the requestType parameter is missing, the request is for a specific device (Master or Slave), so the deviceDesc parameter is REQUIRED. The length of the value MUST NOT exceed 64 octets. See IANA Ruleset Registry, Initial Registry Contents (Section 9.1.2) for ruleset specifics. other: Rulesets and database implementations may require additional request parameters. The Database MUST ignore all parameters it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.4.4. AVAIL_SPECTRUM_BATCH_RESP The response message for the batch Available Spectrum Query contains a schedule of available spectrum for the Device at multiple locations. Chen, et al. Expires October 26, 2014 [Page 23] Internet-Draft paws-protocol April 2014 +---------------------------------------+ |AVAIL_SPECTRUM_BATCH_RESP | +----------------------------+----------+ |timestamp:string | required | |deviceDesc:DeviceDescriptor | required | |geoSpectrumSpecs:list | required |-------+ |............................|..........| | |databaseChange:DbUpdateSpec | optional | | |*other:any | optional | | +----------------------------+----------+ | 0..* V +---------------------------------+ |GeoSpectrumSpec | +----------------------+----------+ |location:GeoLocation | required | |spectrumSpecs:list | required | +----------------------+----------+ Parameters: timestamp: Timestamp of the response of the form, YYYY-MM- DDThh:mm:ssZ, as defined by Date and Time on the Internet: Timestamps [RFC3339]. This can be used by the Device as a reference for the start and stop times in the spectrum schedules. deviceDesc: The Database MUST include the DeviceDescriptor (Section 5.2) specified in the AVAIL_SPECTRUM_BATCH_REQ message. geoSpectrumSpecs: The geoSpectrumSpecs (Section 5.15) list is REQUIRED (although it MAY be empty if spectrum is unavailable). For each location, the Database MAY return one or more SpectrumSpec (Section 5.9) parameters to represent available spectrum for one or more rulesets. The Database MAY return available spectrum for fewer locations than requested. The order of the entries in the list is not significant and the Device MUST use the location value in each GeoSpectrumSpec entry to match available spectrum to a location. databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) parameter to notify the Device of a change to the Database URI, providing one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding database with the list of alternate URIs. other: Database implementations MAY return additional parameters in the response. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters and requirements they place on the Device. See Update Requirements (Section 4.4.2.1) for when the Device must update its available spectrum data. Chen, et al. Expires October 26, 2014 [Page 24] Internet-Draft paws-protocol April 2014 4.4.5. SPECTRUM_USE_NOTIFY The spectrum-use notification message indicates the spectrum anticipated to be used by the device. +--------------------------------------------+ |SPECTRUM_USE_NOTIFY | +---------------------------------+----------+ |deviceDesc:DeviceDescriptor | required | |location:GeoLocation | required | |masterDeviceDesc:DeviceDescriptor| optional | |masterDeviceLocation:GeoLocation | optional | |spectra:list | required |-------+ |............................................| | |*other:any | optional | | +---------------------------------+----------+ | 0..* V +--------------------------------+ |Spectrum | +---------------------+----------+ |resolutionBwHz:float | required | |profiles:list | required | +---------------------+----------+ Parameters: deviceDesc: The DeviceDescriptor (Section 5.2) for the Device is REQUIRED. location: The GeoLocation (Section 5.1) for the Device. When the notification is made by a Master Device on its own behalf, the location is that of the Master Device and is REQUIRED. When the notification is made by a Master Device on behalf of a Slave Device, the location is that of the Slave Device and is OPTIONAL, but may be required by some rulesets. spectra: The Spectrum (Section 5.11) list is REQUIRED, and specifies the spectrum anticipated to be used by the Device, which includes profiles of frequencies and power levels. The list MAY be empty, if the Device decides not to use any spectrum. For consistency, the resolution bandwidth value, "resolutionBwHz" MUST match that from one of the Spectrum (Section 5.11) elements in the corresponding AVAIL_SPECTRUM_RESP message, and the maximum power levels in the Spectrum element MUST be expressed as power over the specified "resolutionBwHz" value. The actual bandwidth to be used (as computed from the start and stop frequencies) MAY be different from the "resolutionBwHz" value. As an example, when the ruleset expresses maximum power spectral density in terms of maximum power over any 100 kHz band, then the "resolutionBwHz" value should be set to 100 kHz, even though the actual bandwidth used can be 20 Chen, et al. Expires October 26, 2014 [Page 25] Internet-Draft paws-protocol April 2014 kHz. masterDeviceDesc: When the notification is made by the Master Device on behalf of a Slave Device, the Master Device MAY provide its own descriptor. masterDeviceLocation: When the notification is made by the Master Device on behalf of a Slave Device, the Master Device MAY include its own GeoLocation (Section 5.1). other: Depending on the ruleset, other parameters may be required. To simplify its logic, the Device MAY include the union of all parameters required by all supported rulesets. The Database MUST ignore all parameters it does not understand. 4.4.6. SPECTRUM_USE_RESP The spectrum-use response message simply acknowledges receipt of the notification. +---------------------------------------+ |SPECTRUM_USE_RESP | +----------------------------+----------+ |databaseChange:DbUpdateSpec | optional | |.......................................| |*other:any | optional | +----------------------------+----------+ Parameters: databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) parameter to notify the Device of a change to the Database URI, providing one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding database with the list of alternate URIs. other: Database implementations MAY return additional parameters in the response. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 4.5. Device Validation Typically, a Slave Device needs a Master Device to ask the Database on its behalf for available spectrum. Depending on the ruleset, the Master Device also must validate with the Database that the Slave Device is permitted to operate. When the ruleset allows a Master Device to "cache" the available spectrum for a period of time, the Master Device may use the simpler Device Validation component, instead of the full Available Spectrum Query component, to validate a Slave Device. Chen, et al. Expires October 26, 2014 [Page 26] Internet-Draft paws-protocol April 2014 When validating one or more Slave Devices, the Master Device sends the Database a request that includes the device identifier -- and any other parameters required by the ruleset -- for each Slave Device. The Database MUST return a response with an entry for each device to indicate whether it is permitted to use the spectrum. A typical sequence for using the Device Validation request is illustrated in Figure 6, where the Master Device already has a valid set of available spectrum for Slave Devices. Note that the communication and protocol between the Slave Device and Master Device is outside the scope of this document. o DEV_VALID_REQ (Section 4.5.1) is the device-validation request message o DEV_VALID_RESP (Section 4.5.2) is the device-validation response message +------------+ +---------------+ +-------------------+ |Slave Device| | Master Device | | Spectrum Database | +------------+ +---------------+ +-------------------+ | | | | AVAIL_SPEC_REQ | | |................>| | | | | | | DEV_VALID_REQ | | |-------------------------->| | | | | | DEV_VALID_RESP | | |<--------------------------| | AVAIL_SPEC_RESP | | |<................| | | | | | (SPECTRUM_USE) | | |................>| (SPECTRUM_USE_NOTIFY) | | |-------------------------->| | | | | | (SPECTRUM_USE_RESP) | | |<--------------------------| Figure 6 Chen, et al. Expires October 26, 2014 [Page 27] Internet-Draft paws-protocol April 2014 4.5.1. DEV_VALID_REQ +---------------------------------------------+ |DEV_VALID_REQ | +----------------------------------+----------+ |deviceDescs:list | required |---+ |masterDeviceDesc:DeviceDescriptor | optional | | +----------------------------------+----------+ | V 1..* +----------------------+ |DeviceDescriptor | +----------------------+ Parameters: deviceDescs: A DeviceDescriptor (Section 5.2) list is REQUIRED, which specifies the list of Slave Devices that are to be validated. masterDeviceDesc: The Master Device MAY provide its own descriptor. 4.5.2. DEV_VALID_RESP +---------------------------------------+ |DEV_VALID_RESP | +----------------------------+----------+ |deviceValidities:list | required |---- |databaseChange:DbUpdateSpec | optional | | +----------------------------+----------+ | V 1..* +---------------------------------------+ |DeviceValidity | +----------------------------+----------+ |deviceDesc:DeviceDescriptor | required | |isValid:boolean | required | |reason:string | optional | +----------------------------+----------+ Parameters: deviceValidities: A DeviceValidities (Section 5.16) list is REQUIRED to report the list of Slave Devices and whether each listed Device is valid. The number of entries MUST match the number of DeviceDescriptors (Section 5.2) listed in the DEV_VALID_REQ message. Chen, et al. Expires October 26, 2014 [Page 28] Internet-Draft paws-protocol April 2014 databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) parameter to notify the Device of a change to the Database URI, providing one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding database with the list of alternate URIs. 5. Protocol Parameters This section presents more details of the parameters that make up the PAWS request and response messages. It also includes a sub-section defining response codes. 5.1. GeoLocation This parameter is used to specify the geo-location of the Device. It may be used to specify one of the following: o A single point with optional uncertainty o A region described by a polygon These are represented using geometric shapes defined in Section 5 of GEOPRIV Presence Information Data Format Location Object [RFC5491], where: o A "point" with uncertainty is represented using the Ellipse shape o A region is represented using the Polygon shape The coordinates are expressed using the WGS84 datum [WGS-84], and units are degrees or meters. The parameter MAY also include a confidence level, expressed as a percentage. The confidence and uncertainty parameters may be required by some rulesets. The data model for GeoLocation is illustrated below: +------------------------------------+ |GeoLocation | +------------------+-----------------+ |point:Ellipse | see description | |region:Polygon | see description | |confidence:int | optional | +------------------+-----------------+ Note: point and region are mutually exclusive. Exactly one must be present. Chen, et al. Expires October 26, 2014 [Page 29] Internet-Draft paws-protocol April 2014 +-------------------------------+ |Ellipse | +--------------------+----------+ |center:Point | required |--+ |semiMajorAxis:float | optional | | |semiMinorAxis:float | optional | | |orientation:float | optional | | +--------------------+----------+ v +---------------------------+ |Point | +----------------+----------+ |latitude:float | required | |longitude:float | required | +----------------+----------+ +-------------------------------+ |Polygon | +-------------------+-----------+ 4..* +---------------------------+ |exterior:list | required |------>|Point | +-------------------+-----------+ +----------------+----------+ |latitude:float | required | |longitude:float | required | +----------------+----------+ Parameters: point: If present, it indicates that the GeoLocation represents a point. Paradoxically, a "point" is parameterized using an Ellipse, where the center represents the location of the point and the distances along the major and minor axes represent the uncertainty. The uncertainty values may be required, depending on the ruleset. Exactly one of "point" or "region" MUST be present. region: If present, it indicates that the GeoLocation represents a region. Exactly one of "point" or "region" MUST be present. center: The center refers to the location of a GeoLocation point and is represented as the center of an ellipse. latitude, longitude: Floating-point numbers that express the latitude and longitude in degrees using the WGS84 datum [WGS-84]. semiMajorAxis, semiMinorAxis: The location uncertainty, expressed in meters, is OPTIONAL. It is parameterized using distances along the major and minor axes of the ellipse. The default value is 0. orientation: This defines the orientation of the ellipse, expressed as the rotation, in degrees, of the semi-major axis from North towards the East. For example, when the uncertainty is greatest along the North-South direction, orientation is 0 degrees; conversely, if the uncertainty is greatest along the East-West direction, orientation is 90 degrees. When orientation is not Chen, et al. Expires October 26, 2014 [Page 30] Internet-Draft paws-protocol April 2014 present, the default value is 0. exterior: When GeoLocation describes a region, the "exterior" field refers to a list of latitude/longitude points that represents the vertices of a polygon. The first and last points MUST be the same. Thus, a minimum of 4 points is required. The following polygon restrictions from [RFC5491] apply: * A connecting line MUST NOT cross another connecting line of the same polygon. * The vertices MUST be defined in a counter-clockwise direction. * The edges of a polygon are defined by the shortest path between two points in space (not a geodesic curve). Consequently, the length between two adjacent vertices SHOULD be restricted to a maximum of 130 km. * All vertices are assumed to be at the same altitude. * Polygon shapes SHOULD be restricted to a maximum of 15 vertices (16 points that includes the repeated vertex). confidence: The location confidence level, as a percentage, MAY be provided. When the parameter is not provided, the default value is 95. Valid values range from 0 to 100, but, in practice, 100- percent confidence is not achievable. The confidence value is meaningful only when GeoLocation refers to a point with uncertainty. 5.2. DeviceDescriptor The device descriptor contains parameters that identify the specific device, such as its manufacturer serial number, manufacturer's ID, and any other device characteristics required by ruleset. +--------------------------------+ |DeviceDescriptor | +---------------------+----------+ |serialNumber:string | required | |manufacturerId:string| optional | |modelId:string | optional | 1..* |rulesetIds:list | optional |------>string |.....................|..........| |*other:any | optional | +---------------------+----------+ Parameters: serialNumber: The manufacturer's device serial number is REQUIRED. The length of the value MUST NOT exceed 64 octets, conforming to the X.520 [ITUT.X520.2008] recommendations. Chen, et al. Expires October 26, 2014 [Page 31] Internet-Draft paws-protocol April 2014 manufacturerId: The manufacturer's ID is OPTIONAL, but may be required by some rulesets. This represents the name of the device manufacturer, and therefore ought to be consistent across all devices from the same manufacturer and distinct from that of other manufacturers. The string value MUST NOT exceed 64 octets in length. modelId: The device's model ID is OPTIONAL, but may be required by some rulesets. The string value MUST NOT exceed 64 octets in length. rulesetIds: The list of identifiers for rulesets supported by the device (see Ruleset ID Registry (Section 9.1)). A Database MAY require that the device provides this list before servicing the device requests. If the Database does not support any of the rulesets specified in the list, the Database MAY refuse to service the device requests. See RulesetInfo (Section 5.6) for discussion on ruleset identifier. If present, the list MUST contain at least one entry. other: Depending on the ruleset, other parameters may be required. The Database MUST ignore all parameters in the message it does not understand. See PAWS Parameters Registry (Section 9.2) for additional valid parameters and for the process for extending the message with more parameters. Additionally, see PAWS Ruleset ID Registry (Section 9.1) for the valid set of parameters for each ruleset. 5.3. AntennaCharacteristics Antenna characteristics provide additional information, such as the antenna height, antenna type, etc. Whether antenna characteristics must be provided in a request depends on the device type and ruleset. Additionally, a parameter marked as optional may be required by some rulesets. +------------------------------------+ |AntennaCharacteristics | +-------------------------+----------+ |height:float | optional | |heightType:enum | optional | |heightUncertainty:float | optional | |.........................|..........| |*characteristics: | optional | | various | | +-------------------------+----------+ Parameters: Chen, et al. Expires October 26, 2014 [Page 32] Internet-Draft paws-protocol April 2014 height: The antenna height in meters. Note that the height may be negative. heightType: Valid values are: AGL Above ground level (default) AMSL Above mean sea level heightUncertainty: The height uncertainty in meters. NOTE: Depending on the ruleset, additional antenna characteristics may be required, such as: o antenna direction o antenna radiation pattern o antenna gain o antenna polarization These are not defined by the base protocol, but may be added to the PAWS Parameters Registry (Section 9.2), as needed. 5.4. DeviceCapabilities Device capabilities provide additional information that may be used by the Device to provide additional information to the Database that can help it to determine available spectrum. If the Database does not support device capabilities it MUST ignore the parameter altogether. +-------------------------------+ |DeviceCapabilities | +---------------------+---------+ |frequencyRanges:list |optional |--+ |.....................|.........| | |*other:any |optional | | +---------------------+---------+ | 0..* V +--------------------------------+ |FrequencyRange | +----------------------+---------+ |startHz:float |required | |stopHz:float |required | +----------------------+---------+ Parameters: frequencyRanges: Optional FrequencyRange (Section 5.13) list. Each FrequencyRange element contains start and stop frequencies in which the Device can operate. When specified, the Database SHOULD NOT return available spectrum that falls outside these ranges. Chen, et al. Expires October 26, 2014 [Page 33] Internet-Draft paws-protocol April 2014 other Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. The Database MUST ignore all parameters it does not understand. 5.5. DeviceOwner This parameter contains device-owner information required as part of device registration. Some rulesets may require additional parameters. +-----------------------------+ |DeviceOwner | +------------------+----------+ |owner:vcard | required | |operator:vcard | optional | +------------------+----------+ Parameters: owner: The vCard contact information for the individual or business that owns the Device is REQUIRED. operator: The vCard contact information for the device operator is OPTIONAL, but may be required by specific rulesets. NOTE: Depending on the ruleset, the Database may be required to validate the device-owner information. In these cases, the Database MUST respond with an INVALID_VALUE error (see Error Codes (Section 5.17)) if validation fails. See PAWS Ruleset ID Registry (Section 9.1) for ruleset-specific requirements on mandatory vCard properties. All contact information MUST be expressed using the structure defined by the vCard Format Specification [RFC6350]. Note that the vCard specification defines maximum lengths for each field, conforming to X.520 [ITUT.X520.2008] recommendations. 5.6. RulesetInfo This contains parameters for the ruleset of a regulatory domain that is communicated using the Initialization component (Section 4.2), Device Registration (Section 4.3), and Available Spectrum Query (Section 4.4) components. Chen, et al. Expires October 26, 2014 [Page 34] Internet-Draft paws-protocol April 2014 +------------------------------------------+ |RulesetInfo | +------------------------------------------+ |authority:string | required | |rulesetId:string | required | |maxLocationChange:float | see description | |maxPollingSecs:int | see description | |..........................................| |*other:any | optional | +------------------------+-----------------+ Parameters: authority: A string that indicates the regulatory domain to which the ruleset applies is REQUIRED. It will normally be a 2-letter country code defined by Country Codes - ISO 3166 [ISO3166-1]. rulesetId: The ID of a ruleset for the specified authority (see Ruleset ID Registry (Section 9.1)). The Device can use this to determine additional device behavior required by the associated ruleset. To define new ruleset IDs, see Defining Ruleset Identifiers (Section 8.1). maxLocationChange: The maximum location change in meters is REQUIRED for Initialization Response (Section 4.2.2), but OPTIONAL otherwise. Some regulatory domains mandate that, when the Device changes location by more than this specified distance, it contact the Database to get the available spectrum for the new location. If this value is provided by the Database within the context of an Available Spectrum Response (Section 4.4.2), it takes precedence over the value within the Initialization Response (Section 4.2.2). maxPollingSecs: The maximum duration, in seconds, between requests for available spectrum is REQUIRED for the Initialization Response (Section 4.2.2), but OPTIONAL otherwise. The Device MUST contact the Database to get available spectrum no less frequently than this duration. If this value is provided within the context of an Available Spectrum Response (Section 4.4.2), it takes precedence over the value within the Initialization Response (Section 4.2.2). other: This message is intended to be extensible with other ruleset- specific parameters. Devices MUST ignore all parameters in the message it does not understand. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 5.7. DbUpdateSpec This element is provided by the Database to notify devices of an upcoming change to the Database URI. Chen, et al. Expires October 26, 2014 [Page 35] Internet-Draft paws-protocol April 2014 +-------------------------------+ |DbUpdateSpec | +---------------------+---------+ +--------------------------+ |databases:list |required |------>|DatabaseSpec | +---------------------+---------+ 1..* +---------------+----------+ |name:string | required | |uri:string | required | +---------------+----------+ Parameters: databases: List of one or more DatabaseSpec (Section 5.8) entries. A Device needs to update its preconfigured list of databases to replace (only) the database that provided the response with the specified entries. 5.8. DatabaseSpec This element contains the name and URI of a database. +--------------------------+ |DatabaseSpec | +---------------+----------+ |name:string | required | |uri:string | required | +---------------+----------+ Parameters: name: The display name for a database. It MAY contain UTF-8. The value length MUST NOT exceed 64 octets. uri: The corresponding URI of the database. The value length MUST NOT exceed 1024 octets. 5.9. SpectrumSpec The SpectrumSpec element encapsulates the schedule of available spectrum for a ruleset. Chen, et al. Expires October 26, 2014 [Page 36] Internet-Draft paws-protocol April 2014 +---------------------------------------+ |SpectrumSpec | +----------------------------+----------+ |rulesetInfo:RulesetInfo | required | |spectrumSchedules:list | required |-----+ |timeRange:EventTime | optional | | |frequencyRanges:list | optional | | |needsSpectrumReport:boolean | optional | | |maxTotalBwHz:float | optional | | |maxContiguousBwHz:float | optional | | +----------------------------+----------+ | | 1..* V +-------------------------------+ |SpectrumSchedule | +--------------------+----------+ |eventTime:EventTime | required | |spectra:list | required | +--------------------+----------+ Parameters: rulesetInfo: The RulesetInfo (Section 5.6) is REQUIRED to identify the regulatory domain and ruleset for which the spectrum schedule applies (see Ruleset ID Registry (Section 9.1)). The Device needs to use the corresponding ruleset to interpret the response. Values provided within this parameter, such as maxLocationChange, take precedence over the values provided by the Initialization Procedure (Section 4.2). spectrumSchedules: The SpectrumSchedule (Section 5.10) list is REQUIRED. At least one schedule MUST be included. More than one schedule MAY be included to represent future changes to the available spectrum. How far in advance a schedule may be provided depends on the ruleset. If more than one schedule is included, the eventTime intervals MUST be disjoint and MUST be sorted in increasing time. A gap in the time schedule indicates no available spectrum during that time-interval gap. timeRange: The time range for which the specification is comprehensive is OPTIONAL. When specified, any gaps in time intervals within the "spectrumSchedules" element that overlaps with the range specified by "timeRange" are interpreted by the Device as time intervals in which there is available spectrum. frequencyRanges: The frequency ranges for which the specification is comprehensive is OPTIONAL. It is a list of disjoint FrequencyRange (Section 5.13) entries. When specified, it typically corresponds to the frequency ranges governed by the ruleset, e.g., for TV whitespace, the frequency ranges can correspond to the VHF and UHF bands of the associated regulatory Chen, et al. Expires October 26, 2014 [Page 37] Internet-Draft paws-protocol April 2014 domain. A Device can combine this information with the available- spectrum specification within the "spectrumSchedules" element to distinguish between "unavailable spectrum" and "spectrum for which no information has been provided". needsSpectrumReport: The Database MAY return true for this parameter if spectrumSchedules list is non-empty; otherwise, the Database MAY omit this parameter altogether, in which case, the default value is false. If this parameter is present and its value is true, the Device sends a SPECTRUM_USE_NOTIFY (Section 4.4.5) message to the Database; otherwise, the Device SHOULD NOT send the SPECTRUM_USE_NOTIFY message. Some rulesets mandate this value to be true. maxTotalBwHz: The Database MAY return a constraint on the maximum total bandwidth (in Hertz) allowed, which may or may not be contiguous. Some rulesets mandate the Database to return this parameter. When present in the response, the Device needs to apply this constraint to its spectrum-selection logic to ensure total bandwidth does not exceed this value. maxContiguousBwHz: The Database MAY return a constraint on the maximum contiguous bandwidth (in Hertz) allowed. Some rulesets mandate the Database to return this parameter. When present in the response, the Device needs to apply this constraint to its spectrum-selection logic to ensure no single block of spectrum has bandwidth that exceeds this value. 5.10. SpectrumSchedule The SpectrumSchedule element combines EventTime (Section 5.14) with Spectrum (Section 5.11) to define a time period in which the spectrum is valid. +-------------------------------+ |SpectrumSchedule | +--------------------+----------+ |eventTime:EventTime | required | +--------------------+ |spectra:list | required |------->|Spectrum | +--------------------+----------+ 0..* +--------------------+ |resolutionBwHz:float| |profiles:list | +--------------------+ Parameters: eventTime: The EventTime (Section 5.14) is REQUIRED to express "when" this specification is valid. Chen, et al. Expires October 26, 2014 [Page 38] Internet-Draft paws-protocol April 2014 spectra: The Spectrum (Section 5.11) list is REQUIRED to specify the available spectrum and permissible power levels, one per resolutionBwHz. The list MAY be empty when there is no available spectrum. 5.11. Spectrum Available spectrum can be characterized by an ordered list of spectrum profiles that defines permissible power levels over a set of frequency ranges. Each Spectrum element defines permissible power levels as maximum power spectral densities over a specified resolution bandwidth, "resolutionBwHz". Note that the spectrum profiles represent the "availability mask", as defined by the governing rule set; they are not intended to encode device-level transmission-mask requirements. o To support a ruleset that defines different "wide-band" and "narrow-band" power levels, PAWS allows multiple Spectrum elements to be included in the available-spectrum response, each with a different resolution bandwidth. o When multiple Spectrum elements are included in the response, each represents a constraint that the Device must satisfy (logical AND). o Each Spectrum element covers the range of frequencies governed by a ruleset, rather than splitting the frequencies across multiple Spectrum elements for the same resolution bandwidth. o Each spectrum profile represents the maximum permissible power spectral density over a contiguous range of frequencies. o When multiple spectrum profiles are included, they MUST be disjoint and MUST be ordered in non-decreasing frequency value. o Gaps in frequencies between consecutive spectrum profiles represent unavailability for those frequencies. The following figure illustrates the Spectrum element and the SpectrumProfile list. Chen, et al. Expires October 26, 2014 [Page 39] Internet-Draft paws-protocol April 2014 +-------------------------------+ |Spectrum | +---------------------+---------+ |resolutionBwHz:float |required | |profiles:list |required |---+ +---------------------+---------+ | 0..* V +-----------------------------+ |SpectrumProfile | +-------------------+---------+ |list |required | +-------------------+---------+ | V 2..* +----------------+---------+ |hz:float |required | |dbm:float |required | +----------------+---------+ Parameters: resolutionBwHz: This parameter defines the resolution bandwidth (in Hertz) over which permissible power spectral density is defined. For example, FCC regulation would require one spectrum specification at a bandwidth of 6MHz, and ETSI regulation would require two specifications, at 0.1MHz and 8MHz. profiles: A SpectrumProfile (Section 5.12) list specifies permissible power levels over a set of frequency ranges. The list MAY be empty if there is no available spectrum. Consider the following example with two different sets of permitted power spectral densities for the same set of frequencies over different resolution bandwidths (for illustrative purposes only): Chen, et al. Expires October 26, 2014 [Page 40] Internet-Draft paws-protocol April 2014 [ { "resolutionBwHz": 6e6, "profiles": [ [ {"hz": 5.18e8, "dbm": 30.0}, {"hz": 5.24e8, "dbm": 30.0} ], ... ] }, { "resolutionBwHz": 1e5, "profiles": [ [ {"hz": 5.18e8, "dbm": 27.0}, {"hz": 5.24e8, "dbm": 27.0} ], ... ] } ] This is interpreted as: o Over any 6MHz within the frequency range, [518MHz, 524MHz), maximum permitted power is 30.0dBm (1000mW), and o Over any 100 kHz within the frequency range, [518MHz, 524MHz), maximum permitted power is 27.0dBm (500mW) This would allow, for example, operating two 100kHz sub-channels within the indicated 6MHz range at 500mW each, totaling 1000mW. Of course, many combinations are possible, as long as they satisfy both conditions. The following example encodes multiple (two) spectrum profiles, each having a gap from 530 MHz to 536 MHz (for illustrative purposes only): Chen, et al. Expires October 26, 2014 [Page 41] Internet-Draft paws-protocol April 2014 [ { "resolutionBwHz": 6e6, "profiles": [ [ {"hz": 5.18e8, "dbm": 30.0}, {"hz": 5.24e8, "dbm": 30.0}, {"hz": 5.24e8, "dbm": 36.0}, {"hz": 5.30e8, "dbm": 36.0} ], [ {"hz": 5.36e8, "dbm": 30.0}, {"hz": 5.42e8, "dbm": 30.0} ], ... ] }, { "resolutionBwHz": 1e5, "profiles": [ [ {"hz": 5.18e8, "dbm": 27.0}, {"hz": 5.24e8, "dbm": 27.0}, {"hz": 5.24e8, "dbm": 30.0}, {"hz": 5.30e8, "dbm": 30.0} ], [ {"hz": 5.36e8, "dbm": 27.0}, {"hz": 5.42e8, "dbm": 27.0} ], ... ] } ] 5.12. SpectrumProfile A spectrum profile is characterized by an ordered list of (frequency, power) points that represents the shape of maximum permissible power levels over a range of frequencies. o It MUST contain a minimum of two entries. o The entries in the list MUST be ordered in non-decreasing frequency values. o Two consecutive points MAY have the same frequency value to represent a "step function". Chen, et al. Expires October 26, 2014 [Page 42] Internet-Draft paws-protocol April 2014 o Three or more points MUST NOT share the same frequency value. o The first frequency is inclusive; the last frequency is exclusive. The following figure illustrates the SpectrumProfile element. +-------------------------------+ |SpectrumProfile | +---------------------+---------+ |list |required |---+ +---------------------+---------+ | 2..* V +----------------+---------+ |hz:float |required | |dbm:float |required | +----------------+---------+ Parameters of each point in the profile: hz: The frequency, in Hertz, at which the power level is defined. dbm: The power level, expressed as dBm per resolution bandwidth, as defined by the "resolutionBwHz" element of the enclosing Spectrum (Section 5.11) element. 5.13. FrequencyRange The FrequencyRange parameter specifies a frequency range. +--------------------------------+ |FrequencyRange | +----------------------+---------+ |startHz:float |required | |stopHz:float |required | +----------------------+---------+ Parameters: startHz: The inclusive start of the frequency range (in Hertz) is REQUIRED. stopHz: The exclusive end of the frequency range (in Hertz) is REQUIRED. 5.14. EventTime The EventTime element specifies the start and stop times of an "event". This is used to indicate the time period for which a Spectrum (Section 5.11) is valid. Chen, et al. Expires October 26, 2014 [Page 43] Internet-Draft paws-protocol April 2014 +---------------------------+ |EventTime | +-----------------+---------+ |startTime:string |required | |stopTime:string |required | +-----------------+---------+ Parameters: startTime: The inclusive start of the event is REQUIRED. stopTime: The exclusive end of the event is REQUIRED. Both times are expressed using the format, YYYY-MM-DDThh:mm:ssZ, as defined by Date and Time on the Internet: Timestamps [RFC3339]. The times MUST be expressed using UTC. A device that does not have access to the current date and time MUST use the timestamp at the top-level of the response message as a substitute for the current time (see Available Spectrum Response (Section 4.4.2) and Available Spectrum Batch Response (Section 4.4.4)). E.g., o (startTime - timestamp) gives the duration that a device must wait before the event becomes "active". If the value is zero or negative, the event is already active. o If the event is already active, (stopTime - timestamp) is the duration that the event remains active. If the value is zero or negative, the event is no longer active and MUST be ignored. 5.15. GeoSpectrumSpec The GeoSpectrumSpec element encapsulates the available spectrum for a location. It is returned within a AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) batch response that contains multiple GeoSpectrumSpec entries, each matching a location provided in the batch request. +----------------------------------+ |GeoSpectrumSpec | +-----------------------+----------+ |location:GeoLocation | required | |spectrumSpecs:list | required |-------+ +-----------------------+----------+ | | 1..* V +--------------+ | SpectrumSpec | +--------------+ Parameters: Chen, et al. Expires October 26, 2014 [Page 44] Internet-Draft paws-protocol April 2014 location: The GeoLocation (Section 5.1) identifies the location at which the spectrum schedule applies. spectrumSpecs: The SpectrumSpec (Section 5.9) list is REQUIRED. At least one entry MUST be included. Each entry represents schedules of available spectrum for a ruleset. More than one entry MAY be included to support multiple rulesets at a location. 5.16. DeviceValidity The DeviceValidity element is used to indicate whether a device is valid. See Section 4.5.2. +---------------------------------------+ |DeviceValidity | +----------------------------+----------+ |deviceDesc:DeviceDescriptor | required | |isValid:boolean | required | |reason:string | optional | +----------------------------+----------+ Parameters: deviceDesc: The DeviceDescriptor (Section 5.2) that was used to check for validity is REQUIRED. isValid: This is a REQUIRED boolean value that indicates whether the Device is valid. reason: If the device identifier is not valid, the Database MAY include a reason. The reason MAY be in any language and contain UTF-8 characters. The length of the value MUST NOT exceed 128 octets. 5.17. Error Element If the Database responds to a PAWS request message with an error, it MUST include an Error element. +----------------------------------+ |Error | +----------------+-----------------+ |code:int | required | |message:string | optional | |data:any | see description | +----------------+-----------------+ Parameters: Chen, et al. Expires October 26, 2014 [Page 45] Internet-Draft paws-protocol April 2014 code: An integer code that indicates the error type is REQUIRED. Values MUST be within the range, -32768 to 32767, inclusive. message: A description of the error is OPTIONAL. It MAY be in any language and contain UTF-8 characters. The length of the value MUST NOT exceed 128 octets. data: The Database MAY include additional data. For some errors, additional data may be required (see Table 1). The Device MUST ignore any data parameters it does not understand. The following table lists predefined and reserved error codes. They are loosely grouped into the following categories: -100s: Indicates compatibility issues, e.g., version mismatch, unsupported or unimplemented features. -200s: Indicates that the Device request contains an error that needs to be modified before making another request. -300s: Indicates authorization-related issues. Values that are not defined explicitly in the Error Codes Table (Table 1) below are unassigned. To define new error codes, see PAWS Error Code Registry (Section 9.3). Code Name Description & Additional parameters ------ ---------------- --------------------------------------------- 0 (reserved) -100 (reserved) -101 VERSION The Database does not support the specified version of the message. -102 UNSUPPORTED The Database does not support the Device. For example, it does not support the ruleset specified in the request. -103 UNIMPLEMENTED The Database does not implement the optional request or optional feature. -104 OUTSIDE_COVERAGE The specified geo-location is outside the coverage area of the Database. The Database MAY include a DbUpdateSpec (Section 5.7) parameter to provide a list of alternate databases that might be appropriate for the requested location. See OUTSIDE_COVERAGE Error (Section 5.17.1) for more details. Chen, et al. Expires October 26, 2014 [Page 46] Internet-Draft paws-protocol April 2014 -105 DATABASE_CHANGE The Database has changed its URI. The Database MAY include a DbUpdateSpec (Section 5.7) parameter in the error response to provide devices with one or more alternate database URIs. The Device needs to use the information to update its list of preconfigured databases to replace (only) its entry for the responding Database with the list of alternate database URIs. See DATABASE_CHANGE Error (Section 5.17.2) for more details. -200 (reserved) -201 MISSING A required parameter is missing. The Database MUST include a list of the required parameter names. The Database MAY include only names of parameters that are missing, but MAY include a full list. Including the full list of missing parameters may reduce the number of re-queries from the Device. See MISSING Error (Section 5.17.3) for more details. -202 INVALID_VALUE A parameter value is invalid in some way. The Database SHOULD include a message indicating which parameter and why its value is invalid. -300 (reserved) -301 UNAUTHORIZED The Device is not authorized to used the Database. Authorization may be determined by the ruleset or be dependent on prior arrangement between the Device and Database. -302 NOT_REGISTERED Device registration required, but the Device is not registered. -32000 (reserved) Reserved for JSON-RPC error codes. to -32768 Table 1: Error Codes 5.17.1. OUTSIDE_COVERAGE Error When the error code is OUTSIDE_COVERAGE, the Database MAY include an ErrorData element within its as the "data" field, and, if present, the ErrorData contains a DbUpdateSpec (Section 5.7) element that provides a list of alternate databases that might be appropriate for the requested location. Chen, et al. Expires October 26, 2014 [Page 47] Internet-Draft paws-protocol April 2014 +---------------------------+ |Error | +----------------+----------+ |code:int | required | |message:string | optional | +-----------------------------+ |data:ErrorData | optional |--->|ErrorData | +----------------+----------+ +------------------+----------+ |spec:DbUpdateSpec | optional | +------------------+----------+ 5.17.2. DATABASE_CHANGE Error When the error code is DATABASE_CHANGE, the Database MAY include an ErrorData element within its Error response as the "data" field, and, if present, the ErrorData contains a DbUpdateSpec (Section 5.7) element that provides a list of alternate databases. +---------------------------+ |Error | +----------------+----------+ |code:int | required | |message:string | optional | +-----------------------------+ |data:ErrorData | optional |--->|ErrorData | +----------------+----------+ +------------------+----------+ |spec:DbUpdateSpec | required | +------------------+----------+ 5.17.3. MISSING Error When the error code is MISSING, the Database MUST include an ErrorData element within its Error response as the "data" field, and the ErrorData element MUST include a list of the missing required parameters and MAY include the list of all required parameters. +---------------------------+ |Error | +----------------+----------+ |code:int | required | |message:string | optional | +---------------------------+ |data:ErrorData | required |--->|ErrorData | +----------------+----------+ +----------------+----------+ 1..* |parameters:list | required |--+ +----------------+----------+ | v string Parameters: Chen, et al. Expires October 26, 2014 [Page 48] Internet-Draft paws-protocol April 2014 parameters: List of one or more parameter names (strings). The name of a parameter is expressed using dotted notation, when appropriate, e.g., "deviceDesc.serialNumber". 6. Message Encoding The PAWS protocol is encoded using JSON-RPC [JSON-RPC] (see also The JavaScript Object Notation (JSON) Data Interchange Format [RFC7159]). Each component described in Protocol Functionalities (Section 4) corresponds to one or more JSON-RPC methods. This section provides the JSON schema for each of the protocol messages and parameters defined in sections Protocol Functionalities (Section 4) and Protocol Parameters (Section 5). JSON schemas are expressed using the format described by JSON Schema [I-D.zyp-json-schema], but are not intended to be used for formal validation. NOTE: In general, all messages defined in this section are extensible by adding additional properties to support ruleset-specific and database-specific requirements. In all cases, the Device or Database MUST ignore any parameter it does not understand. NOTE: The JSON examples in this section may contain ellipses (...) to represent additional properties or elements that have been omitted in order to make the examples more concise. 6.1. JSON-RPC Binding The JSON-RPC [JSON-RPC] protocol consists of two basic objects, Request and Response: o The JSON-RPC Request object encapsulates a PAWS functionality (operation) and the request message o The JSON-RPC Response object encapsulates a PAWS response message and Error element The Database and Device MUST support JSON-RPC 2.0 encoding. The JSON-RPC Request for PAWS has the following form: { "jsonrpc": "2.0", "method": "string", "params": , "id": "string" } where "method" is the name of a PAWS functionality (operation), and represents one of the PAWS request objects associated with Chen, et al. Expires October 26, 2014 [Page 49] Internet-Draft paws-protocol April 2014 the method. Method names are defined with the prefix, "spectrum.paws.". The non-error JSON-RPC Response for PAWS has the following form: { "jsonrpc": "2.0", "result": , "id": "string" } where represents one of the PAWS response objects associated with the method. The error JSON-RPC Response for PAWS has the following form: { "jsonrpc": "2.0", "error": { "code": "integer", "message": "string", "data": "object" }, "id": "string" } where the Error object and error codes are described by Error Element (Section 5.17). The Database SHOULD attempt to use the most specific applicable PAWS error code. When an accurate one is not available, it SHOULD fall back to standard JSONRPC error codes as defined in JSONRPC specification. For example, if the Database receives invalid JSON from the Device, it should respond with "-32700", signifying a parse error. As a last resort, the Database MAY send a suitable HTTP 5xx response. Depending on prior arrangement between a Database and Device, the Request and Response objects MAY contain additional parameters. The Database or Device MUST ignore all parameters it does not understand. 6.2. init Method This section describes the encoding for the JSON-RPC "spectrum.paws.init" method that represents the Initialization functionality (Section 4.2). Chen, et al. Expires October 26, 2014 [Page 50] Internet-Draft paws-protocol April 2014 6.2.1. INIT_REQ Parameters The JSON encoding of the Initialization request message INIT_REQ (Section 4.2.1) is described by the following schema: { "name": "INIT_REQ", "type": "object", "properties": { "type": "INIT_REQ", "version": { "type": "string", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "required": true }, "location": { "type": "GeoLocation", "description": "The location of the Device's antenna. Some rulesets mandate this to be the Device's current location; others allow it to be an anticipated position of the Device.", "required": true } } } Example "init" JSON-RPC request: Chen, et al. Expires October 26, 2014 [Page 51] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "method": "spectrum.paws.init", "params": { "type": "INIT_REQ", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "location": { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } } }, "id": "xxxxxx" } 6.2.2. INIT_RESP Parameters The JSON encoding of the Initialization response message INIT_RESP (Section 4.2.2) is described by the following schema: Chen, et al. Expires October 26, 2014 [Page 52] Internet-Draft paws-protocol April 2014 { "name": "INIT_RESP", "type": "object", "properties": { "type": "INIT_RESP", "version": { "type": "string", "required": true }, "rulesetInfos": { "type": "array", "description": "List of rulesets and associated attributes that govern the device at the location specified by the device. The list MUST have at least one entry.", "items": "RulesetInfo", "required": true }, "databaseChange": { "type": "DbUpdateSpec", "description": "Indicates that the Database URI will be changing. Devices need to update their configurations", "required": false } } } Example "init" JSON-RPC response: { "jsonrpc": "2.0", "result": { "type": "INIT_RESP", "version": "1.0", "rulesetInfos": [ { "authority": "us", ... }, ... ] }, "id": "xxxxxx" } Chen, et al. Expires October 26, 2014 [Page 53] Internet-Draft paws-protocol April 2014 6.3. register Method This section describes the encoding for the JSON-RPC "spectrum.paws.register" method that represents Device Registration functionality (Section 4.3). 6.3.1. REGISTRATION_REQ Parameters The JSON encoding of the Registration request message REGISTRATION_REQ (Section 4.3.1) is described by the following schema: { "name": "REGISTRATION_REQ", "type": "object", "properties": { "type": "REGISTRATION_REQ", "version": { "type": "string", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "required": true }, "location": { "type": "GeoLocation", "description": "The location of the Device's antenna.", "required": true }, "deviceOwner": { "type": "DeviceOwner", "required": true }, "antenna": { "type": "AntennaCharacteristics", "description": "Antenna characteristics, including its height and height type", "required": false } } } Example "register" JSON-RPC request: Chen, et al. Expires October 26, 2014 [Page 54] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "method": "spectrum.paws.register", "params": { "type": "REGISTRATION_REQ", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "deviceOwner": { "owner": [ "vcard", [ ["version", {}, "text", "4.0"], ["kind", {}, "text", "org"], ["fn", {}, "text", "Racafrax, Inc."] ] ], "operator": [ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "John Frax"], ["adr", {}, "text", ["", "", "100 Main Street", "Summersville", "CA", "90034", "USA" ] ], ["tel", {}, "uri", "tel:+1-213-555-1212"], ["email", {}, "text", "j.frax@rackafrax.com"] ] ] }, "location": { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } }, "antenna": {"height": 10.2, "heightType": "AGL"} }, "id": "xxxxxx" } 6.3.2. REGISTRATION_RESP Parameters The JSON encoding of the Registration response message REGISTRATION_RESP (Section 4.3.2) is described by the following schema: Chen, et al. Expires October 26, 2014 [Page 55] Internet-Draft paws-protocol April 2014 { "name": "REGISTRATION_RESP", "type": "object", "properties": { "type": "REGISTRATION_RESP", "version": { "type": "string", "required": true }, "rulesetInfos": { "type": "array", "description": "List of rulesets for which device registration was successful. The list MUST have at least one entry.", "items": "RulesetInfo", "required": true }, "databaseChange": { "type": "DbUpdateSpec", "description": "Indicates that the Database URI will be changing. Devices need to update their configurations", "required": false } } } Example "register" JSON-RPC response: { "jsonrpc": "2.0", "result": { "type": "REGISTRATION_RESP", "version": "1.0", "rulesetInfos": [ { "authority": "us", ... } ] }, "id": "xxxxxx" } 6.4. getSpectrum Method This section describes the encoding for the JSON-RPC "spectrum.paws.getSpectrum" method that represents the single- location query of the Available Spectrum Query functionality Chen, et al. Expires October 26, 2014 [Page 56] Internet-Draft paws-protocol April 2014 (Section 4.4) that enables a Device to obtain a set of available spectrum from the Database. 6.4.1. AVAIL_SPECTRUM_REQ Parameters The JSON encoding of the Available Spectrum request message AVAIL_SPECTRUM_REQ (Section 4.4.1) is described by the following schema: { "name": "AVAIL_SPECTRUM_REQ", "type": "object", "properties": { "type": "AVAIL_SPECTRUM_REQ", "version": { "type": "string", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "description": "Descriptor of the device for which to determine available spectrum.", "required": false }, "location": { "type": "GeoLocation", "description": "The location of the Device's antenna. Some rulesets mandate this to be the Device's current location; others allow it to be an anticipated position of the Device. When the request is made by a Master Device on behalf of a Slave Device, this is the location of the Slave Device (optional), and the Master Device location is provided in the masterDeviceLocation parameter.", "required": false }, "owner": { "type": "DeviceOwner", "description": "May be required if the Device is not yet registered or if the DB does not implement a separate device-registration request.", "required": false }, "antenna": { "type": "AntennaCharacteristics", "description": "Antenna characteristics, including its height and height type.", "required": false Chen, et al. Expires October 26, 2014 [Page 57] Internet-Draft paws-protocol April 2014 }, "capabilities": { "type": "DeviceCapabilities", "description": "The Database SHOULD NOT return spectrum that is incompatible with the specified capabilities.", "required": false }, "masterDeviceDesc": { "type": "DeviceDescriptor", "description": "When the request is made by a Master Device on behalf of a Slave Device, this is the descriptor of the Master Device.", "required": false }, "masterDeviceLocation": { "type": "GeoLocation", "description": "When the request is made by a Master Device on behalf of a Slave Device, this is the location of the Master Device.", "required": false }, "requestType": { "type": "string", "description": "Optional value that modifies the request. Valid values depends on ruleset.", "required": false } } } Example "getSpectrum" JSON-RPC request: Chen, et al. Expires October 26, 2014 [Page 58] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "method": "spectrum.paws.getSpectrum", "params": { "type": "AVAIL_SPECTRUM_REQ", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "location": { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } }, "antenna": {"height": 10.2, "heightType": "AGL"} }, "id": "xxxxxx" } 6.4.2. AVAIL_SPECTRUM_RESP Parameters The JSON encoding of the Available Spectrum response message AVAIL_SPECTRUM_RESP (Section 4.4.2) is described by the following schema: Chen, et al. Expires October 26, 2014 [Page 59] Internet-Draft paws-protocol April 2014 { "name": "AVAIL_SPECTRUM_RESP", "type": "object", "properties": { "type": "AVAIL_SPECTRUM_RESP", "version": { "type": "string", "required": true }, "timestamp": { "type": "string", "description": "Timestamp of the response, using YYYY-MM-DDThh:mm:ssZ RFC3339 format. This SHOULD be used by the Device as a reference for the start and stop times in the spectrum schedule", "format": "date-time", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "required": true }, "spectrumSpecs": { "type": "array", "description": "The Database MAY return more than one SpectrumSpec to represent available spectrum for multiple rulesets at the specified location.", "items": "SpectrumSpec", "required": true }, "databaseChange": { "type": "DbUpdateSpec", "description": "Indicates that the Database URI will be changing. Devices need to update their configurations", "required": false } } } The following example "getSpectrum" JSON-RPC response contains: o A schedule with two time ranges o A spectrum profile for one resolution bandwidth (6 MHz) The schemas for these (and other) nested objects may be found in the Sub-message Schemas (Section 6.8) section. { Chen, et al. Expires October 26, 2014 [Page 60] Internet-Draft paws-protocol April 2014 "jsonrpc": "2.0", "result": { "type": "AVAIL_SPECTRUM_RESP", "version": "1.0", "timestamp": "2013-03-02T14:30:21Z", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "spectrumSpecs": [ { "rulesetInfo": { "authority": "us", ... }, "needsSpectrumReport": false, "spectrumSchedules": [ { "eventTime": { "startTime": "2013-03-02T14:30:21Z", "stopTime": "2013-03-02T20:00:00Z" }, "spectra": [ { "resolutionBwHz": 6e6, "profiles": [ ... [ {"hz":5.18e8, "dbm":30.0}, {"hz":5.36e8, "dbm":30.0}, {"hz":5.36e8, "dbm":36.0}, {"hz":5.42e8, "dbm":36.0} ], [ {"hz":6.20e8, "dbm":30.0}, {"hz":6.26e8, "dbm":30.0} ], ... ] } ] }, { "eventTime": { "startTime": "2013-03-02T22:00:00Z", "stopTime": "2013-03-03T14:30:21Z" }, Chen, et al. Expires October 26, 2014 [Page 61] Internet-Draft paws-protocol April 2014 "spectra": [ ... ] } ] } ] }, "id": "xxxxxx" } The following example "getSpectrum" JSON-RPC response includes a spectrum profile that contains specifications for two different bandwidth resolutions (6 MHz and 100 kHz): { "jsonrpc": "2.0", "result": { "type": "AVAIL_SPECTRUM_RESP", "version": "1.0", "timestamp": "2013-03-02T14:30:21Z", "deviceDesc": { "serialNumber": "XXX", ... }, "spectrumSpecs": [ { "rulesetInfo": { "authority": "xx", ... }, "needsSpectrumReport": false, "spectrumSchedules": [ { "eventTime": { "startTime": "2013-03-02T14:30:21Z", "stopTime": "2013-03-02T20:00:00Z" }, "spectra": [ { "resolutionBwHz": 6e6, "profiles": [ ... [ {"hz":5.18e8, "dbm":30.0}, {"hz":5.36e8, "dbm":30.0}, {"hz":5.36e8, "dbm":36.0}, {"hz":5.42e8, "dbm":36.0} Chen, et al. Expires October 26, 2014 [Page 62] Internet-Draft paws-protocol April 2014 ], [ {"hz":6.20e8, "dbm":30.0}, {"hz":6.26e8, "dbm":30.0} ], ... ] }, { "resolutionBwHz": 1e5, "profiles": [ ... [ {"hz":5.18e8, "dbm":27.0}, {"hz":5.36e8, "dbm":27.0}, {"hz":5.36e8, "dbm":30.0}, {"hz":5.42e8, "dbm":30.0} ], [ {"hz":6.20e8, "dbm":27.0}, {"hz":6.26e8, "dbm":27.0} ], ... ] } ] }, { "eventTime": { "startTime": "2013-03-02T22:00:00Z", "stopTime": "2013-03-03T14:30:21Z" }, "spectra": [ ... ] } ] } ] }, "id": "xxxxxx" } 6.5. getSpectrumBatch Method This section describes the encoding for the JSON-RPC "spectrum.paws.getSpectrumBatch" method that represents the multiple- location query of the Available Spectrum Query functionality Chen, et al. Expires October 26, 2014 [Page 63] Internet-Draft paws-protocol April 2014 (Section 4.4) that enables a Device to obtain a set of available spectrum for multiple locations from the Database. 6.5.1. AVAIL_SPECTRUM_BATCH_REQ Parameters The JSON encoding of the Batch Available Spectrum request AVAIL_SPECTRUM_BATCH_REQ (Section 4.4.3) is described by the following schema. This an OPTIONAL feature of the Database. { "name": "AVAIL_SPECTRUM_BATCH_REQ", "type": "object", "properties": { "type": "AVAIL_SPECTRUM_BATCH_REQ", "version": { "type": "string", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "description": "Descriptor of the device for which to determine available spectrum.", "required": true }, "locations": { "type": "array", "description": "At least one device location is required. Additional (anticipated) locations can also be included, as permitted by the ruleset. When the request is made by a Master Device on behalf of a Slave Device, these are locations of the Slave Device.", "items": "GeoLocation", "required": true }, "owner": { "type": "DeviceOwner", "description": "May be required if the Device is not yet registered or if the DB does not implement a separate device-registration request.", "required": false }, "antenna": { "type": "AntennaCharacteristics", "description": "Antenna characteristics, including its height and height type.", "required": false }, "capabilities": { Chen, et al. Expires October 26, 2014 [Page 64] Internet-Draft paws-protocol April 2014 "type": "DeviceCapabilities", "description": "The Database SHOULD NOT return spectrum that is incompatible with the specified capabilities.", "required": false }, "masterDeviceDesc": { "type": "DeviceDescriptor", "description": "When the request is made by a Master Device on behalf of a Slave Device, this is the descriptor of the Master Device.", "required": false }, "masterDeviceLocation": { "type": "GeoLocation", "description": "When the request is made by a Master Device on behalf of a Slave Device, this is the location of the Master Device.", "required": false }, "requestType": { "type": "string", "description": "Optional value that modifies the request. Valid values depends on the ruleset.", "required": false } } } Example "getSpectrumBatch" JSON-RPC request: Chen, et al. Expires October 26, 2014 [Page 65] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "method": "spectrum.paws.getSpectrumBatch", "params": { "type": "AVAIL_SPECTRUM_BATCH_REQ", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "locations": [ { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } }, { "point": { "center": {"latitude": 37.0005, "longitude": -101.3005} } }, ... ], "antenna": {"height": 10.2, "heightType": "AGL"} }, "id": "xxxxxx" } 6.5.2. AVAIL_SPECTRUM_BATCH_RESP Parameters The JSON encoding of the Batch Available Spectrum response AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) is described by the following schema: Chen, et al. Expires October 26, 2014 [Page 66] Internet-Draft paws-protocol April 2014 { "name": "AVAIL_SPECTRUM_BATCH_RESP", "type": "object", "properties": { "type": "AVAIL_SPECTRUM_BATCH_RESP", "version": { "type": "string", "required": true }, "timestamp": { "type": "string", "description": "Timestamp of the response, using YYYY-MM-DDThh:mm:ssZ RFC3339 format. This SHOULD be used by the Device as a reference for the start and stop times in the spectrum schedule", "format": "date-time", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "required": true }, "geoSpectrumSpecs": { "type": "array", "description": "A list of locations and available spectrum at each location. For each location, there may be more than one SpectrumSpec element to support more than one ruleset at that location.", "items": "GeoSpectrumSpec", "required": true }, "databaseChange": { "type": "DbUpdateSpec", "description": "Indicates that the Database URI will be changing. Devices need to update their configurations", "required": false } } } The following example "getSpectrumBatch" JSON-RPC response illustrates a batch response that contains spectrum specifications for two locations: { "jsonrpc": "2.0", "result": { "type": "AVAIL_SPECTRUM_BATCH_RESP", Chen, et al. Expires October 26, 2014 [Page 67] Internet-Draft paws-protocol April 2014 "version": "1.0", "timestamp": "2013-03-02T14:30:21Z", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "geoSpectrumSpecs": [ { "location": { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } }, "spectrumSpecs": [ { "rulesetInfo": { "authority": "us", ... }, "needsSpectrumReport": false, "spectrumSchedules": [ { "eventTime": { "startTime": "2013-03-02T14:30:21Z", "stopTime": "2013-03-02T20:00:00Z" }, "spectra": [ { "resolutionBwHz": 6e6, "profiles": [ ... [ {"hz":5.18e8, "dbm":30.0}, {"hz":5.36e8, "dbm":30.0}, {"hz":5.36e8, "dbm":36.0}, {"hz":5.42e8, "dbm":36.0} ], [ {"hz":6.20e8, "dbm":30.0}, {"hz":6.26e8, "dbm":30.0} ], ... ] } ] }, { Chen, et al. Expires October 26, 2014 [Page 68] Internet-Draft paws-protocol April 2014 "eventTime": { "startTime": "2013-03-02T22:00:00Z", "stopTime": "2013-03-03T14:30:21Z" }, "spectra": [ ... ] } ] } ] }, { "location": { "point": { "center": {"latitude": 37.0005, "longitude": -101.3005} } }, "spectrumSpecs": [ ... ] } ] }, "id": "xxxxxx" } 6.6. notifySpectrumUse Method This section describes the encoding for the JSON-RPC "spectrum.paws.notifySpectrumUse" method that represents the Spectrum-usage notification of the Available Spectrum Query functionality (Section 4.4.5) that notifies the Database of anticipated spectrum usage. 6.6.1. SPECTRUM_USE_NOTIFY Parameters The JSON encoding of the Spectrum Notification message SPECTRUM_USE_NOTIFY (Section 4.4.5) is described by the following schema: Chen, et al. Expires October 26, 2014 [Page 69] Internet-Draft paws-protocol April 2014 { "name": "SPECTRUM_USE_NOTIFY", "type": "object", "properties": { "type": "SPECTRUM_USE_NOTIFY", "version": { "type": "string", "required": true }, "deviceDesc": { "type": "DeviceDescriptor", "required": true }, "location": { "type": "GeoLocation", "description": "The location of the Device. When the notification is made by a Master Device on behalf of a Slave Device, this is the location of the Slave Device.", "required": false }, "masterDeviceDesc": { "type": "DeviceDescriptor", "description": "When the notification is made by a Master Device on behalf of a Slave Device, this is the descriptor of the Master Device.", "required": false }, "masterDeviceLocation": { "type": "GeoLocation", "description": "When the notification is made by the Master Device on behalf of a Slave Device, this is the location of the Master Device.", "required": false }, "spectra": { "type": "array", "description": "The spectrum anticipated to be used by the Device.", "items": "Spectrum", "required": true } } } Example "notifySpectrumUse" JSON-RPC notification: Chen, et al. Expires October 26, 2014 [Page 70] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "method": "spectrum.paws.notifySpectrumUse", "params": { "type": "SPECTRUM_USE_NOTIFY", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "location": { "point": { "center": {"latitude": 37.0005, "longitude": -101.3005} } }, "spectra": [ { "resolutionBwHz": 6e6, "profiles": [ [ {"hz":5.18e8, "dbm":30.0}, {"hz":5.24e8, "dbm":30.0} ] ] } ] }, "id": "xxxxxx" } 6.6.2. SPECTRUM_USE_RESP Parameters The JSON encoding of the Spectrum-usage response SPECTRUM_USE_RESP (Section 4.4.6) is described by the following schema: { "name": "SPECTRUM_USE_RESP", "type": "object", "properties": { "type": "SPECTRUM_USE_RESP", "version": { "type": "string", "required": true } } } Chen, et al. Expires October 26, 2014 [Page 71] Internet-Draft paws-protocol April 2014 Example "notifySpectrumUse" JSON-RPC response: { "jsonrpc": "2.0", "result": { "type": "SPECTRUM_USE_RESP", "version": "1.0" }, "id": "xxxxxx" } 6.7. verifyDevice Method This section describes the encoding for the JSON-RPC "spectrum.paws.verifyDevice" method that represents the Device Validation functionality (Section 4.5). This is used by a Master Device to validate Slave Devices. 6.7.1. DEV_VALID_REQ Parameters The JSON encoding of the Device Validation request DEV_VALID_REQ (Section 4.5.1) is described by the following schema: { "name": "DEV_VALID_REQ", "type": "object", "properties": { "type": "DEV_VALID_REQ", "version": { "type": "string", "required": true }, "deviceDescs": { "type": "array", "description": "List of Slave Devices to be validated", "items": "DeviceDescriptor", "required": true } } } Example "verifyDevice" JSON-RPC request: Chen, et al. Expires October 26, 2014 [Page 72] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "method": "spectrum.paws.verifyDevice", "params": { "type": "DEV_VALID_REQ", "version": "1.0", "deviceDescs": [ { "serialNumber": "XXX", "fccId": "YYY", ... }, { "serialNumber": "XXX3", "fccId": "YYY2", ... }, ... ] }, "id": "xxxxxx" } 6.7.2. DEV_VALID_RESP Parameters The JSON encoding of the Device Validation response DEV_VALID_RESP (Section 4.5.2) is described by the following schema: Chen, et al. Expires October 26, 2014 [Page 73] Internet-Draft paws-protocol April 2014 { "name": "DEV_VALID_RESP", "type": "object", "properties": { "type": "DEV_VALID_RESP", "version": { "type": "string", "required": true }, "deviceValidities": { "type": "array", "description": "List of DeviceValidity objects that shows the validity of each device included in the original Device Validity Request message.", "items": "DeviceValidity", "required": true }, "databaseChange": { "type": "DbUpdateSpec", "description": "Indicates that the Database URI will be changing. Devices need to update their configurations", "required": false } } } Example "verifyDevice" JSON-RPC response: Chen, et al. Expires October 26, 2014 [Page 74] Internet-Draft paws-protocol April 2014 { "jsonrpc": "2.0", "result": { "type": "DEV_VALID_RESP", "version": "1.0", "deviceValidities": [ { "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", ... }, "isValid": true }, { "deviceDesc": { "serialNumber": "XXX3", "fccId": "YYY2", ... }, "isValid": false, "reason": "Not authorized" } ] }, "id": "xxxxxx" } 6.8. Sub-message Schemas This section defines the schema for Protocol Parameters (Section 5) embedded in PAWS request and response messages. 6.8.1. GeoLocation This parameter is used to specify the GeoLocation (Section 5.1) of the Device. The geometric shapes represent the JSON encoding shapes defined in GEOPRIV Presence Information Data Format Location Object [RFC5491]. { "name": "GeoLocation", "type": "object", "properties": { "point": { "description": "A single location, with optional uncertainty measures. Exactly one of 'point' or 'region' must be present.", Chen, et al. Expires October 26, 2014 [Page 75] Internet-Draft paws-protocol April 2014 "type": "Ellipse", "required": false }, "region": { "description": "A region described by a polygon. Exactly one of 'point' or 'region' must be present.", "type": "Polygon", "required": false }, "confidence": { "description": "Confidence interval when location is a point with uncertainty. 0 to 100.", "type": "integer", "required": false, "default": 95 } } } { "name": "Point", "type": "object", "properties": { "latitude": { "description": "Double-precision floating-point degrees. WGS84 datum.", "type": "number", "required": true }, "longitude": { "type": "number", "description": "Double-precision floating-point degree. WGS84 datum.", "required": true } } } { "name": "Ellipse", "type": "object", "properties": { "center": { "type": "Point", "required": true }, "semiMajorAxis": { "description": "Floating-point meters that describe location uncertainty along the major axis of the ellipse.", Chen, et al. Expires October 26, 2014 [Page 76] Internet-Draft paws-protocol April 2014 "type": "number", "required": false, "default": 0 }, "semiMinorAxis": { "description": "Floating-point meters that describe location uncertainty along the minor axis of the ellipse.", "type": "number", "required": false, "default": 0 }, "orientation": { "description": "Orientation of the ellipse, as rotation of the major axis from North towards East. Degrees.", "type": "number", "required": false, "default": 0 } } } { "name": "Polygon", "type": "object", "properties": { "exterior": { "description": "List of Points in counter-clockwise order. They MUST form a loop with no edges that cross each other. First and last points MUST be the same. Minimum of 4 points.", "type": "array", "items": "Point", "required": true } } } 6.8.2. DeviceDescriptor The DeviceDescriptor (Section 5.2) contains parameters that identify the specific device, such as its manufacturer serial number, ruleset- specific ID (e.g., FCC ID), and any other device characteristics required by rulesets, such as device-type classification. See Initial PAWS Parameters Registry Contents (Section 9.2.2) for additional valid parameters, e.g., "fccId", "etsiEnDeviceType", etc. Chen, et al. Expires October 26, 2014 [Page 77] Internet-Draft paws-protocol April 2014 { "name": "DeviceDescriptor", "type": "object", "properties": { "serialNumber": { "type": "string", "required": true }, "manufacturerId": { "type": "string", "required": false }, "modelId": { "type": "string", "required": false }, "rulesetIds": { "type": "array", "description": "List of identifiers for rulesets supported by the device.", "items": "string", "required": false } } } 6.8.3. AntennaCharacteristics AntennaCharacteristics (Section 5.3) provide additional information, such as the antenna height, antenna type, etc. Chen, et al. Expires October 26, 2014 [Page 78] Internet-Draft paws-protocol April 2014 { "name": "AntennaCharacteristics", "type": "object", "properties": { "height": { "description": "Height of the antenna, in meters", "type": "number", "required": false }, "heightType": { "description": "Reference type for height: Above Ground Level (AGL), or Above Mean Sea Level (AMSL).", "enum": ["AGL","AMSL"], "default": "AGL", "required": false }, "heightUncertainty": { "description": "Uncertainty of the height measurement, in meters.", "type": "number", "required": false } } } 6.8.4. DeviceCapabilities Device capabilities (Section 5.4) provide additional information that MAY be used by the Device to provide additional information to the Database to help the Database determine available spectrum. If the Database does not support device capabilities, it MUST ignore the parameter. Chen, et al. Expires October 26, 2014 [Page 79] Internet-Draft paws-protocol April 2014 { "name": "DeviceCapabilities", "type": "object", "description": "Device capabilities to help DB determine available spectrum. The DB SHOULD NOT return available spectrum that falls outside the device capabilities.", "properties": { "frequencyRanges": { "type": "array", "description": "The frequency ranges in which the Device can operate.", "items": "FrequencyRange", "required": false } } } 6.8.5. DeviceOwner The DeviceOwner (Section 5.5) parameter contains device-owner information required as part of device registration. Some rulesets require additional parameters and specific fields within a vCard. JSON encoding of vCard is described in jCard: The JSON format for vCard [RFC7095]. { "name": "DeviceOwner", "type": "object", "description": "Device-owner information required as part of Device registration. Rulesets MAY require additional parameters.", "properties": { "owner": { "type": "vCard", "description":"Contact information for the individual or business that owns the device.", "required": true }, "operator": { "type": "vCard", "description":"Contact information for the device operator.", "required": false } } } Example: Chen, et al. Expires October 26, 2014 [Page 80] Internet-Draft paws-protocol April 2014 { "deviceOwner": { "owner": [ "vcard", [ ["version", {}, "text", "4.0"], ["kind", {}, "text", "org"], ["fn", {}, "text", "Racafrax, Inc."] ] ], "operator": [ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "John Frax"], ["adr", {}, "text", ["", "", "100 Main Street", "Summersville", "CA", "90034", "USA" ] ], ["tel", {}, "uri", "tel:+1-213-555-1212"], ["email", {}, "text", "j.frax@rackafrax.com"] ] ] } } 6.8.6. RulesetInfo RulesetInfo (Section 5.6) contains parameters for the ruleset of a regulatory domain that is communicated using the Initialization component (Section 4.2). Chen, et al. Expires October 26, 2014 [Page 81] Internet-Draft paws-protocol April 2014 { "name": "RulesetInfo", "type": "object", "description": "The ruleset of a regulatory domain that is communicated to Devices in the Initialization Response message.", "properties": { "authority": { "type": "string", "description": "The regulatory authority at the specified location. It is a 2-letter country codes defined by ISO3166.", "required": true }, "rulesetId": { "type": "string", "description": "The identifier of an applicable ruleset.", "required": true }, "maxLocationChange": { "type": "number", "description": "Maximum location change in meters.", "required": false }, "maxPollingSecs": { "type": "integer", "description": "Maximum duration, in seconds, between requests for available spectrum.", "required": false } } } 6.8.7. DbUpdateSpec DbUpdateSpec (Section 5.7) contains one or more database specifications. It is used to indicate a change to the Database URI. Chen, et al. Expires October 26, 2014 [Page 82] Internet-Draft paws-protocol April 2014 { "name": "DbUpdateSpec", "type": "object", "description": "Specification for updates to a Database URI", "properties": { "databases": { "type": "array", "description": "The specification of one or more databases.", "item": "DatabaseSpec", "required": true } } } 6.8.8. DatabaseSpec DatabaseSpec (Section 5.8) specifies the name and URI of a database. { "name": "DatabaseSpec", "type": "object", "description": "Specification for a database", "properties": { "name": { "type": "string", "description": "The display name of a database.", "required": true }, "uri": { "type": "string", "description": "The URI of a database.", "required": true } } } 6.8.9. Spectrum Available Spectrum (Section 5.11) can logically be characterized by a list of SpectrumProfiles, each defining the shape of the permissible power levels over a range of frequencies. { "name": "Spectrum", "type": "object", "description": "A per-bandwidth list of frequency ranges with permissible power levels. For example, In US, FCC requires only one spectrum specification at 6MHz Chen, et al. Expires October 26, 2014 [Page 83] Internet-Draft paws-protocol April 2014 bandwidth; ETSI requires two (at 0.1MHz and 8MHz).", "properties": { "resolutionBwHz": { "type": "number", "description": "Resolution bandwidth (Hz) over which permissible power spectral densities are defined.", "required": true }, "profiles": { "type": "array", "description": "List of SpectrumProfile objects to specify permissible power levels, over a set of frequency ranges, for a given resolutionBwHz. The list MAY be empty when there is no available spectrum.", "items": "SpectrumProfile", "required": true } } } { "name": "SpectrumProfile", "type": "array", "description": "A list of (frequency, power) points. A minimum of two entries is required.", "item": "SpectrumProfilePoint" } { "name": "SpectrumProfilePoint", "type": "object", "description": "A point defined by a frequency and power level at that frequency.", "properties": { "hz": { "type": "number", "description": "Frequency (Hz)", "required": true }, "dbm": { "type": "number", "description": "Power (dBm) per resolution bandwidth as defined by enclosing resolutionBwHz.", "required": true } } } Chen, et al. Expires October 26, 2014 [Page 84] Internet-Draft paws-protocol April 2014 The following example Spectrum message for a resolution bandwidth of 6 MHz. This example contains power levels for only two frequency segments: o From 518 MHz to 542 MHz o From 620 MHz to 626 MHz In practice, this message would contain more (frequency, power) points to cover all frequencies governed by the associated ruleset. See the Spectrum (Section 5.11) section for a more detailed discussion on the representation. { "resolutionBwHz": 6e6, "profiles": [ [ {"hz":5.18e8, "dbm":30.0}, {"hz":5.36e8, "dbm":30.0}, {"hz":5.36e8, "dbm":36.0}, {"hz":5.42e8, "dbm":36.0} ], [ {"hz":6.20e8, "dbm":30.0}, {"hz":6.26e8, "dbm":30.0} ] ] } 6.8.10. FrequencyRange The FrequencyRange (Section 5.13) element describes a frequency range and permissible power level within the specified range. { "name": "FrequencyRange", "type": "object", "properties": { "startHz": { "type": "number", "description": "The inclusive start of the frequency range.", "required": true }, "stopHz": { "type": "number", "description": "The exclusive end of the frequency range.", "required": true } } } Chen, et al. Expires October 26, 2014 [Page 85] Internet-Draft paws-protocol April 2014 6.8.11. EventTime The EventTime (Section 5.14) element specifies the start and stop times of an "event." It is used to indicate the time period for which a Spectrum (Section 5.11) is valid. { "name": "EventTime", "type": "object", "properties": { "startTime": { "type": "string", "description": "YYYY-MM-DDThh:mm:ssZ RFC3339 format. Inclusive.", "format": "date-time", "required": false }, "stopTime": { "type": "string", "description": "YYYY-MM-DDThh:mm:ssZ RFC3339 format. Exclusive.", "format": "date-time", "required": false } } } 6.8.12. SpectrumSchedule The SpectrumSchedule (Section 5.10) element combines EventTime with Spectrum to define a time period during which the spectrum is valid. Chen, et al. Expires October 26, 2014 [Page 86] Internet-Draft paws-protocol April 2014 { "name": "SpectrumSchedule", "type": "object", "description": "The SpectrumSchedule element combines EventTime with Spectrum to define a time period during which spectrum is valid.", "properties": { "eventTime": { "type": "EventTime", "description": "Period when the spectra is valid.", "required": true }, "spectra": { "type": "array", "description": "List of available spectra and permissible power levels; one spectrum object per resolutionBwHz. The list MAY be empty when there is no available spectrum.", "items": "Spectrum", "required": true } } } 6.8.13. SpectrumSpec The JSON encoding of the SpectrumSpec (Section 5.9) element is described by the following schema: { "name": "SpectrumSpec", "type": "object", "description": "The SpectrumSpec element represents schedules of available spectrum for a ruleset.", "properties": { "rulesetInfo": { "type": "RulesetInfo", "description": "Indicates the active ruleset and attributes that define the applicable ruleset that govern the device.", "required": false }, "spectrumSchedules": { "type": "array", "description": "The Database MAY return more than one schedule to represent future changes to the available spectrum. This array MAY be empty if no spectrum is available. If more than one is present, the event-time intervals MUST be sorted and MUST be disjoint.", Chen, et al. Expires October 26, 2014 [Page 87] Internet-Draft paws-protocol April 2014 "items": "SpectrumSchedule", "required": true }, "timeRange": { "type": "EventTime", "description": "The time range for which the spectrumSchedules is comprehensive.", "required": false }, "frequencyRanges": { "type": "array", "description": "The frequency ranges for which the spectrumSchedules is comprehensive.", "items": "FrequencyRange", "required": false }, "needsSpectrumReport": { "type": "boolean", "description": "Rulesets that require a spectrum-usage report from devices would mandate the Database to set this value to true.", "default": false, "required": false }, "maxTotalBwHz": { "type": "number", "description": "Constraint on total bandwidth allowed, summed across all blocks of spectrum.", "required": false }, "maxContiguousBwHz": { "type": "number", "description": "Constraint on bandwidth allowed for any single block of spectrum.", "required": false } } } 6.8.14. GeoSpectrumSpec The GeoSpectrumSpec (Section 5.15) element encapsulates the schedule of available spectrum at a location. Chen, et al. Expires October 26, 2014 [Page 88] Internet-Draft paws-protocol April 2014 { "name": "GeoSpectrumSpec", "type": "object", "description": "The GeoSpectrumSpec element encapsulates the schedule of available spectrum at a location.", "properties": { "location": { "type": "GeoLocation", "description": "The location at which the spectrum schedule applies.", "required": true }, "spectrumSpecs": { "type": "array", "description": "At least one element MUST be included. More than one element MAY be included to represent available spectrum for more than one ruleset.", "items": "SpectrumSpec", "required": true } } } 6.8.15. DeviceValidity The DeviceValidity (Section 5.16) element is used to indicate whether a device is valid. See Section 4.5.2. Chen, et al. Expires October 26, 2014 [Page 89] Internet-Draft paws-protocol April 2014 { "name": "DeviceValidity", "type": "object", "description": "The DeviceValidity element specifies whether the device is valid.", "properties": { "deviceDesc": { "type": "DeviceDescriptor", "required": true }, "isValid": { "type": "boolean", "description": "Boolean that indicates if the Device is valid", "required": true }, "reason": { "type": "string", "description": "If the device identifier is not valid, the Database MAY include a reason. The reason MAY be in any language.", "required": false } } } 6.8.16. Additional Properties The Database or Device MAY include additional properties not explicitly listed in the schema elaborated in this document. The Database and Device MUST ignore any such additional properties (and their associated values) that they do not understand. 7. HTTPS Binding This section describes the use of HTTP over TLS (HTTPS) HTTP Over TLS [RFC2818] as the transport mechanism for the PAWS protocol. TLS provides message integrity and confidentiality between the Master Device and the Database. The Master Device MUST implement server authentication, as described in Section 3.1 of HTTP Over TLS [RFC2818]. The Device uses the URI determined (either statically configured or dynamically discovered) to authenticate the server. The Device SHOULD fail a request if server authentication fails. Depending on prior relationship between a database and device, the server MAY require client authentication, as described in the Transport Layer Security (TLS) Protocol [RFC5246], to authenticate Chen, et al. Expires October 26, 2014 [Page 90] Internet-Draft paws-protocol April 2014 the device. To enable databases to handle large numbers of requests from large numbers of devices, the Database MAY support and Devices SHOULD support Stateless TLS Session Resumption [RFC5077]. A PAWS request message is carried in the body of an HTTP POST request. A PAWS response message is carried in the body of an HTTP response. A PAWS response SHOULD include a Content-Length header. The POST method is the only method REQUIRED for PAWS. If a database chooses to support GET, it MUST be an escaped URI, but the encoding of the URI is outside the scope of this document. The database MAY refuse to support the GET request by returning an HTTP error code, such as 404 (not found). The Database MAY redirect a PAWS request by returning a HTTP 3xx response (as defined by HTTP/1.1 [RFC2616]). The Database MUST provide the redirect URI in the Location header of the 3xx response, and the Device MUST handle redirects by using the Location header provided by the Database. When redirecting, the Device MUST observe the delay indicated by the Retry-After header. The Device MUST authenticate the Database that returns the redirect response before following the redirect. Also, the Device MUST authenticate the Database indicated in the redirect. Since the Device may communicate with a Database (which it authenticated) without user interaction, when the response code is 301 (Moved Permanently), the Device MAY redirect without asking a user for confirmation (note that this represents an exception to the HTTP/1.1 [RFC2616] requirements for HTTP POST methods). The Database SHOULD use HTTP status code "307 Temporary Redirect" to indicate that the Device SHOULD resubmit the same request to an alternate URI. The Device MAY revert to the original URI for the very next request, or MAY continue to use the alternate URI for a period of time, e.g.,: o For the remainder of its session, or o For a fixed period of time, or o Until power cycled, or o Until it receives another redirect However, the Device does not need to modify its stored list of URIs. The Database SHOULD use HTTP status code "301 Moved Permanently" to indicate that the Device SHOULD resubmit this request, and all future requests, to an alternate URI. If the Device maintains a list of available URIs, it needs to replace only the current URI with the alternate URI. Chen, et al. Expires October 26, 2014 [Page 91] Internet-Draft paws-protocol April 2014 8. Extensibility 8.1. Defining Ruleset Identifiers A ruleset represents a set of device-side requirements for which the device has been certified. It typically corresponds to, but is not limited to, a set of rules that govern a specific set of radio spectrum for a regulatory domain. Ruleset identifiers are defined and registered in the Ruleset ID Registry following the procedure in Section 9.1. Ruleset ID values MUST conform to the ruleset-id ABNF. If the Ruleset ID requires additional parameters, they MUST be registered in the PAWS Parameters Registry, as described by Section 9.2. ruleset-id = 1*64ruleset-char ruleset-char = ALPHA / DIGIT / "_" / "." When defining a Ruleset ID: o It can be useful for the identifier to be descriptive of the set of rules that allow a device to operate within one or more regulatory domains. For example, it might include the name of a regulatory body or a certification process. o The identifier SHOULD include some sort of version information, such as a year and/or version number. o The identifier MUST NOT exceed 64 characters. 8.2. Defining New Message Parameters New request or response parameters for use with the PAWS protocol are defined and registered in the parameters registry following the procedure in Section 9.2. Parameter names MUST conform to the param-name ABNF and parameter values syntax MUST be well-defined (e.g., using ABNF, or a reference to the syntax of an existing parameter). param-name = 1*64name-char name-char = ALPHA / DIGIT / "_" The parameter name SHOULD be lowerCamelCase. The name MUST NOT exceed 64 characters. Unregistered vendor-specific parameter extensions that are not commonly applicable, and are specific to the implementation details of the Database where they are used SHOULD use a vendor-specific prefix that is not likely to conflict with other registered values (e.g., begin with 'companyname'). Chen, et al. Expires October 26, 2014 [Page 92] Internet-Draft paws-protocol April 2014 8.3. Defining Additional Error Codes Additional error codes MAY be defined to extend the set listed in Section 5.17. Additional error codes are registered, following the procedures in Section 9.3. If the error code requires additional response parameters, they are registered in the PAWS Parameters Registry, as described by Section 9.2. By convention, the error code is a negative integer value, using one of the range of values defined in Error Codes (Section 5.17). If an appropriate category does not exist, it can use values in a different range. 9. IANA Considerations This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of parameters and values related to the PAWS protocol, in accordance with [RFC5226]. There are three registries associated with PAWS: o PAWS Ruleset ID Registry (Section 9.1) o PAWS Parameter Registry (Section 9.2) o PAWS Error Code Registry (Section 9.3) A registrant should contact IANA directly at http://www.iana.org to apply for new registry assignments. Prior to the registration request, the registrant is encouraged to post to the paws-iana-review@ietf.org mailing list, including the specification or its draft, to get early feedback. IANA should consult a Designated Expert for all registration requests. The responsible IESG area director should appoint one or more Designated Experts. The intention is that new registrations will be accompanied by a published specification. But in order to allow for the allocation of values prior to publication of the specification, the Designated Expert can approve allocations once it seems clear that the specification will be published. If the registrant has not already done so, the Designated Expert will post a request to the paws-iana-review@ietf.org mailing list for comment and review, including the specification or its draft. Before a period of 30 days has passed, the Designated Expert will either approve or deny the registration request and publish a notice of the decision to the paws-iana-review@ietf.org mailing list, as well as informing IANA. A denial notice must be justified by an explanation, and in the cases where it is possible, concrete suggestions on how the request can be modified so as to become acceptable should be provided. Chen, et al. Expires October 26, 2014 [Page 93] Internet-Draft paws-protocol April 2014 9.1. PAWS Ruleset ID Registry This specification establishes the PAWS Ruleset ID Registry. Ruleset type names for inclusion in the PAWS protocol messages are registered on the advice of one or more Designated Experts, with Specification Required [RFC5226]. The specification must include a reference to the regulatory rules to which it applies. To increase interoperability, it is desirable to have fewer rulesets than to have many rulesets with small variations. Consequently, the Designated Expert should avoid duplication and should encourage the registrant to look for alternatives if there are only small variations with an existing ruleset. The Designated Expert should ensure that the proposed registration is complete with respect to its associated regulatory rules and may seek an expert familar with those rules to participate in the review on the paws-iana-review@ietf.org mailing list. 9.1.1. Registration Template Ruleset name: The name of the ruleset. It is a string value that contains the name of the regulatory body that established the rules and version information. The length of the string MUST NOT exceed 64 US-ASCII characters. Specification document(s): Reference to the document that specifies the parameter, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant sections also may be included, but is not required. Additional parameter requirements: List of additional parameters to associate with the ruleset ID and any additional requirements on message parameters. New parameters MUST be registered separately in the PAWS Parameters Registry, as described by Section 8.2. 9.1.2. Initial Registry Contents The PAWS Ruleset ID Registry enables protocol extensibility to support any regulatory domain and ruleset. The initial contents of the registry, however, include only FCC-specific and ETSI-specific entries, because, as of this writing, it is the only regulatory domain that has finalized rules. There is no intent to restrict the protocol to FCC rules. The initial contents of the PAWS Ruleset ID Registry are listed below; each section corresponds to a single row in the registry. The PAWS Ruleset ID Registry will include the following fields: 'Ruleset name', 'Additional parameter requirements', and 'Specification document(s)'. IANA will post each registration template that is not included in the text of an RFC. Chen, et al. Expires October 26, 2014 [Page 94] Internet-Draft paws-protocol April 2014 9.1.2.1. Federal Communications Commission (FCC) For the additional parameters that start with the "fcc" prefix, see PAWS Parameters Registry Initial Contents (Section 9.2.2) for more information. Ruleset name: FccTvBandWhiteSpace-2010 Specification document(s): This ruleset refers to the FCC rules for TV-band White Space operations established in the Code of Federal Regulations (CFR), Title 47, Part 15, Subpart H [FCC-CFR47-15H]. Each of the following tables defines additional parameters for the indicated PAWS message. Available Spectrum Request (Section 4.4.1) +---------------+-----------------------------+-------------+-------+ | Parameter | Type | Requirement | Notes | | Name | | | | +---------------+-----------------------------+-------------+-------+ | deviceDesc | DeviceDescriptor | REQUIRED | | | | (Section 5.2) | | | +---------------+-----------------------------+-------------+-------+ Available Spectrum Batch Request (Section 4.4.3) +---------------+-----------------------------+-------------+-------+ | Parameter | Type | Requirement | Notes | | Name | | | | +---------------+-----------------------------+-------------+-------+ | deviceDesc | DeviceDescriptor | REQUIRED | | | | (Section 5.2) | | | +---------------+-----------------------------+-------------+-------+ DeviceDescriptor (Section 5.2) +-------------------+--------+-------------+------------------------+ | Parameter Name | Type | Requirement | Notes | +-------------------+--------+-------------+------------------------+ | fccId | string | REQUIRED | Specifies a device's | | | | | FCC certification ID | | | | | (Section 9.2.2.1). | Chen, et al. Expires October 26, 2014 [Page 95] Internet-Draft paws-protocol April 2014 | fccTvbdDeviceType | string | REQUIRED | Specifies the FCC | | | | | Device Type | | | | | (Section 9.2.2.2) of | | | | | TV-band White Space | | | | | device, as defined by | | | | | the FCC rules. | +-------------------+--------+-------------+------------------------+ The following table lists additional requirements on parameters of the DeviceOwner (Section 5.5) message. DeviceOwner (Section 5.5) +-----------+-------+-----------------------------------------------+ | Parameter | Type | Additional Requirement | | Name | | | +-----------+-------+-----------------------------------------------+ | owner | vCard | The owner MUST contain the formatted name of | | | | an individual or organization using the "fn" | | | | property. When the name is that of an | | | | organization, the entry also MUST contain the | | | | "kind" property, with a value of "org". | | operator | vCard | The operator entry MUST contain the following | | | | properties for the contact person responsible | | | | for the device's operation: "fn", "adr", | | | | "tel", and "email". | +-----------+-------+-----------------------------------------------+ 9.1.2.2. European Telecommunications Standards Institute (ETSI) For the additional parameters that start with the "etsi" prefix, see PAWS Parameters Registry Initial Contents (Section 9.2.2) for more information. Ruleset name: ETSI-EN-301-598-1.0.9-draft Specification document(s): This ruleset refers to the ETSI Harmonised Standard [ETSI-EN-301-598] established by ETSI. Each of the following tables defines additional parameters for the indicated PAWS message. Chen, et al. Expires October 26, 2014 [Page 96] Internet-Draft paws-protocol April 2014 DeviceDescriptor (Section 5.2) +-------------------------+-------+-------------+-------------------+ | Parameter Name | Type | Requirement | Notes | +-------------------------+-------+-------------+-------------------+ | manufacturerId | strin | REQUIRED | Specifies a | | | g | | device's | | | | | manufacturer's | | | | | identifier. MUST | | | | | NOT exceed 64 | | | | | octets. | | modelId | strin | REQUIRED | Specifies a | | | g | | device's model | | | | | identifier. MUST | | | | | NOT exceed 64 | | | | | octets. | | etsiEnDeviceType | strin | REQUIRED | Specifies the | | | g | | device's ETSI | | | | | device type | | | | | (Section 9.2.2.3) | | | | | . | | etsiEnDeviceEmissionsCl | strin | REQUIRED | Specifies the | | ass | g | | device's ETSI | | | | | device emissions | | | | | class | | | | | (Section 9.2.2.4) | | | | | . | | etsiEnTechnologyId | strin | REQUIRED | Specifies the | | | g | | device's ETSI | | | | | technology ID | | | | | (Section 9.2.2.5) | | | | | . | | etsiEnDeviceCategory | strin | REQUIRED | Specifies the | | | g | | device's ETSI | | | | | device category | | | | | (Section 9.2.2.6) | | | | | . | +-------------------------+-------+-------------+-------------------+ AVAIL_SPECTRUM_REQ (Section 4.4.1) Chen, et al. Expires October 26, 2014 [Page 97] Internet-Draft paws-protocol April 2014 +-------------+--------+-------------+------------------------------+ | Parameter | Type | Requirement | Notes | | Name | | | | +-------------+--------+-------------+------------------------------+ | requestType | string | OPTIONAL | Modifies the | | | | | available-spectrum request | | | | | type. If specified, the only | | | | | valid value is, "Generic | | | | | Slave", and the Database | | | | | MUST respond with generic | | | | | operating parameters for any | | | | | Slave Device. | +-------------+--------+-------------+------------------------------+ Available Spectrum Batch Request (Section 4.4.3) +-------------+--------+-------------+------------------------------+ | Parameter | Type | Requirement | Notes | | Name | | | | +-------------+--------+-------------+------------------------------+ | requestType | string | OPTIONAL | Modifies the | | | | | available-spectrum request | | | | | type. If specified, the only | | | | | valid value is, "Generic | | | | | Slave", and the Database | | | | | MUST respond with generic | | | | | operating parameters for any | | | | | Slave Device. | +-------------+--------+-------------+------------------------------+ The following tables define additional requirements for the DeviceDescriptor (Section 5.2) and RulesetInfo (Section 5.6) parameters that appear in the AVAIL_SPECTRUM_RESP (Section 4.4.2) and AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) messages. DeviceDescriptor (Section 5.2) Chen, et al. Expires October 26, 2014 [Page 98] Internet-Draft paws-protocol April 2014 +--------------------------------+-------+----------+---------------+ | Parameter Name | Type | Requirem | Notes | | | | ent | | +--------------------------------+-------+----------+---------------+ | needsSpectrumReport | boole | REQUIRED | The Database | | | an | | MUST set this | | | | | to true to | | | | | indicate that | | | | | the Device | | | | | must report | | | | | spectrum | | | | | usage. | | maxTotalBwHz | float | REQUIRED | Specifies a | | | | | constraint on | | | | | total allowed | | | | | bandwidth. | | maxContiguousBwHz | float | REQUIRED | Specifies a | | | | | constraint on | | | | | total allowed | | | | | contiguous | | | | | bandwidth. | | etsiEnSimultaneousChannelOpera | strin | OPTIONAL | Specifies a | | tionRestriction | g | | constraint on | | | | | simultaneous | | | | | channel | | | | | operation | | | | | (Section 9.2. | | | | | 2.7). If it | | | | | is not | | | | | provided, the | | | | | default value | | | | | is "0". | +--------------------------------+-------+----------+---------------+ RulesetInfo (Section 5.6) +-------------------+-------+-------------+-------------------------+ | Parameter Name | Type | Requirement | Notes | +-------------------+-------+-------------+-------------------------+ | maxLocationChange | float | OPTIONAL | Specifies a constraint | | | | | on maximum location | | | | | changes. | +-------------------+-------+-------------+-------------------------+ Chen, et al. Expires October 26, 2014 [Page 99] Internet-Draft paws-protocol April 2014 9.2. PAWS Parameters Registry This specification establishes the PAWS Parameters Registry. Additional parameters for inclusion in the PAWS protocol requests, responses, or sub-messages are registered on the advice of one or more Designated Experts, with Specification Required [RFC5226]. The Designated Expert should avoid duplication, i.e., avoid adding a new parameter when an existing one suffices. When a set of parameters is added in support of a new ruleset (Section 9.1), the parameters should share a common prefix that reflects the ruleset ID. The prefix may be omitted, of course, if a parameter has more general applicability. 9.2.1. Registration Template Parameter name: The name of the parameter (e.g., "example"). Parameter usage location: The location(s) where the parameter can be used. The possible locations are the named requests, responses, and messages defined in Protocol Functionalities (Section 4) and Protocol Parameters (Section 5). Specification document(s): Reference to the document that specifies the parameter, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant sections also may be included, but is not required. 9.2.2. Initial Registry Contents The PAWS Parameters Registry enables protocol extensibility to support any regulatory domain and ruleset. The initial contents of the registry, however, include only FCC-specific and ETSI-specific entries, because, as of this writing, they are the only regulatory domains that have established rules. There is no intent to restrict the protocol to FCC and ETSI rules. The PAWS Parameters Registry's initial contents are listed below; each section corresponds to a row of the registry. The PAWS Parameters Registry will include the following fields: 'Parameter name', 'Parameter usage location', and 'Specification document(s)'. IANA will post each registration template that is not included in the text of an RFC. 9.2.2.1. FCC ID Chen, et al. Expires October 26, 2014 [Page 100] Internet-Draft paws-protocol April 2014 Parameter name: fccId Parameter usage location: DeviceDescriptor (Section 5.2) Specification document(s): [[ this document ]] Specifies the device's FCC certification identifier. The value is an identifier string whose length MUST NOT exceed 32 US-ASCII characters. Note that, in practice, a valid FCC ID may be limited to 19 characters, as proposed in FCC Administration Topics Review [FCC-Review-2012-10]. 9.2.2.2. FCC Device Type Parameter name: fccTvbdDeviceType Parameter usage location: DeviceDescriptor (Section 5.2) Specification document(s): [[ this document ]] Specifies the TV Band White Space device type, as defined by the FCC. Valid values are "FIXED", "MODE_1", "MODE_2". 9.2.2.3. ETSI Device Type Parameter name: etsiEnDeviceType Parameter usage location: DeviceDescriptor (Section 5.2) Specification document(s): Specifies the White Space Device type, as defined by the ETSI Harmonised Standard [ETSI-EN-301-598]. Valid values are single-letter strings, such as "A", "B", etc. Consult the documentation for details about the device types. 9.2.2.4. ETSI Device Emissions Class Parameter name: etsiEnDeviceEmissionsClass Parameter usage location: DeviceDescriptor (Section 5.2) Specification document(s): Specifies the White Space Device emissions class, as defined by the ETSI Harmonised Standard [ETSI-EN-301-598], that characterises the out-of-block emissions of the device. The values are represented by numeric strings, such as "1", "2", "3", etc. Consult the documentation for details about emissions classes 9.2.2.5. ETSI Technology Identifier Parameter name: etsiEnTechnologyId Parameter usage location: DeviceDescriptor (Section 5.2) Specification document(s): Specifies the White Space Device technology identifier, as defined by the ETSI Harmonised Standard [ETSI-EN-301-598]. The string value MUST NOT exceed 64 octets in length. Consult the documentation for valid values. Chen, et al. Expires October 26, 2014 [Page 101] Internet-Draft paws-protocol April 2014 9.2.2.6. ETSI Device Category Parameter name: etsiEnDeviceCategory Parameter usage location: DeviceDescriptor (Section 5.2) Specification document(s): Specifies the White Space Device category, as defined by the ETSI Harmonised Standard [ETSI-EN-301-598]. Valid values are the strings, "master" and "slave". It is case insensitive. 9.2.2.7. ETSI Simultaneous Channel Operation Restriction Parameter name: etsiEnSimultaneousChannelOperationRestriction Parameter usage location: SpectrumSpec (Section 5.9) Specification document(s): Specifies the constraint on the device maximum total EIRP, as defined by the ETSI Harmonised Standard [ETSI-EN-301-598]. The values are represented by numeric strings, such as "0", "1", etc. Consult the documentation for the specification of the power constraint corresponding to each parameter value. 9.3. PAWS Error Code Registry This specification establishes the PAWS Error Code Registry. Additional error codes for inclusion in the PAWS protocol error message are registered on the advice of one or more Designated Experts, with Specification Required [RFC5226]. Error codes are intended to be used for automated error handling by devices. Before approval, the Designated Expert should consider whether a device would handle the new error code differently from an existing error code, or whether the difference could be communicated effectively to the end-user via the "reason" parameter of the Error (Section 5.17) object. 9.3.1. Registration Template Code: Integer value of the error code. The value MUST be an unassigned value in the range -32768 to 32767, inclusive. Name: Name of the error. Description: Description of the error and its associated parameters, if any. Additional parameters: Additional parameters that are returned in the data portion of the error (See Section 5.17). New parameters MUST be registered separately in the PAWS Parameters Registry, as described by Section 9.2. Chen, et al. Expires October 26, 2014 [Page 102] Internet-Draft paws-protocol April 2014 9.3.2. Initial Registry Contents Initial registry contents are defined in the Table of Error Codes (Table 1). Note that the third column, "Description & Additional parameters", contains both the description of the error code and the specification of additional parameters, when applicable. The PAWS Error Code Registry will include the following fields: 'Code', 'Name', 'Description', and 'Additional parameters'. The registry will also include the error-code categories describing -100s, -200s, and -300s as a note (see Error Codes (Section 5.17)). IANA will post each registration template that is not included in the text of an RFC. 10. Security Considerations PAWS is a protocol whereby a Master Device requests a schedule of available spectrum at its location (or location of its Slave Devices) before it (they) can operate using those frequencies. Whereas the information provided by the Database must be accurate and conform to the applicable ruleset, the Database cannot enforce, through the protocol, that a client device uses only the spectrum it provided. In other words, devices can put energy in the air and cause interference without asking the Database. Hence, PAWS security considerations do not include protection against malicious use of the White Space spectrum. For more detailed information on specific requirements and security considerations associated with PAWS, see Protocol to Access White Space database: PAWS Use Cases and Requirements [RFC6953]. By using the PAWS protocol, the Master Device and the Database expose themselves to the following risks: o Accuracy: The Master Device receives incorrect spectrum- availability information. o Privacy: An unauthorized entity intercepts identifying data for the Master Device or its Slave Devices, such as serial number and location. Protection from these risks depends on the success of the following steps: 1. The Master Device must determine the address of a proper database. 2. The Master Device must connect to the proper database. 3. The Database must determine or compute accurate spectrum- availability information. Chen, et al. Expires October 26, 2014 [Page 103] Internet-Draft paws-protocol April 2014 4. PAWS messages must be transmitted unmodified between the Database and the Master Device. 5. PAWS messages must be encrypted between the Database and the Master Device to prevent exposing private information. 6. For a Slave Device, the spectrum-availability information also must be transmitted unmodified and secure between the Master Device and the Slave Device. Of these, only steps 1, 2, 4, and 5 are within the scope of this document. This document addresses Step 1 by allowing static provisioning of one or more trusted Databases; dynamic provisioning is out of scope. Step 3 is dependent on specific database implementations and rulesets and is outside the scope of this document. Step 6 requires a protocol between master and slave devices and is thus outside the scope of this document. 10.1. Assurance of Proper Database This document assumes that the Database is contacted using a domain name or an IP address. Using HTTP over TLS HTTP Over TLS [RFC2818], the Database authenticates its identity, either as a domain name or IP address, to the Master Device by presenting a certificate containing that identifier as a "subjectAltName" (i.e., as a dNSName or IP address). If the Master Device has external information as to the expected identity or credentials of the proper database (e.g., a certificate fingerprint), these checks MAY be omitted. Note that in order for the presented certificate to be valid at the client, the client must be able to validate the certificate. In particular, the validation path of the certificate must end in one of the client's trust anchors, even if that trust anchor is the Database certificate itself. A Master Device should allow for the fact that a Database can change its certificate authorities (CAs) over time. 10.2. Protection Against Modification To prevent a PAWS response message from being modified en route, messages must be transmitted over an integrity-protected channel. Using HTTP over TLS, the channel will be protected by appropriate cypher suites. 10.3. Protection Against Eavesdropping Using HTTP over TLS, messages protected by appropriate cypher suites are also protected from eavesdropping or otherwise access by unauthorized parties en route. Chen, et al. Expires October 26, 2014 [Page 104] Internet-Draft paws-protocol April 2014 10.4. Client Authentication Considerations Although the Database can inform a device of available spectrum it can use, the Database cannot enforce that the Master Device uses any/ only those frequencies. Indeed, a malicious device can operate without ever contacting a database. Consequently, client authentication is not required for the core PAWS protocol (although it may be required by specific regulatory domains). Depending on a prior relationship between a Database and Master Device, the Database MAY require client authentication. TLS provides client authentication, but there are some considerations: o As indicated in Section 3.2 of HTTP Over TLS [RFC2818], the TLS client authentication procedure only determines that the device has a certificate chain rooted in an appropriate CA (or a self- signed certificate). The database would not know what the client identity ought to be, unless it has some external source of information. Distribution and management of such information, including revocation lists, are outside the scope of this document. o Authentication schemes are secure only to the extent that secrets or certificates are kept secure. When there are a vast number of deployed devices using PAWS, the possibility that device keys will not leak becomes small. Implementations should consider how to manage the system in the eventuality that there is a leak. 11. Contributors This document draws heavily from the following Internet Draft documents, [I-D.das-paws-protocol] and [I-D.wei-paws-framework]. The editor would like to specifically call out and thank the contributing authors of these two documents. Donald Joslyn Spectrum Bridge Inc. 1064 Greenwood Blvd. Lake Mary, FL 32746 U.S.A. Email: d.joslyn at spectrumbridge dot com Xinpeng Wei Huawei Phone: +86 13436822355 Email: weixinpeng@huawei.com Chen, et al. Expires October 26, 2014 [Page 105] Internet-Draft paws-protocol April 2014 12. Acknowledgments The authors gratefully acknowledge the contributions of: Gabor Bajko, Ray Bellis, Teco Boot, Nancy Bravin, Rex Buddenberg, Gerald Chouinard, Stephen Farrell, Michael Fitch, Joel M. Halpern, Daniel Harasty, Michael Head, Jussi Kahtava, Warren Kumari, Kalle Kulsmanen, Paul Lambert, Andy Lee, Anthony Mancuso, Basavaraj Patil, Scott Probasco, Brian Rosen, Andy Sago, Peter Stanforth, John Stine, and Juan Carlos Zuniga. 13. References 13.1. Normative References [JSON-RPC] "JSON-RPC 2.0 Specification", . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, "Transport Layer Security (TLS) Session Resumption without Server-Side State", RFC 5077, January 2008. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations", RFC 5491, March 2009. [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, Chen, et al. Expires October 26, 2014 [Page 106] Internet-Draft paws-protocol April 2014 August 2011. [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, January 2014. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. 13.2. Informative References [ETSI-EN-301-598] European Telecommunication Standards Institute (ETSI), "Final draft ETSI EN 301 598 (V1.0.9): White Space Devices (WSD); Wireless Access Systems operating in the 470 MHz to 790 MHz frequency band; Harmonized EN covering the essential requirements of article 3.2 of the R&TTE Directive", February 2014, . [FCC-CFR47-15H] U. S. Government, "Electronic Code of Federal Regulations, Title 47, Part 15, Subpart H: Television Band Devices", December 2010, . [FCC-Review-2012-10] Federal Communications Commission, "Administration Topics Review", October 2012, . [I-D.das-paws-protocol] Das, S., Malyar, J., and D. Joslyn, "Device to Database Protocol for White Space", draft-das-paws-protocol-02 (work in progress), July 2012. [I-D.wei-paws-framework] Wei, X., Zhu, L., and P. McCann, "PAWS Framework", draft-wei-paws-framework-00 (work in progress), July 2012. [I-D.zyp-json-schema] Galiegue, F., Zyp, K., and G. Court, "JSON Schema: core definitions and terminology", draft-zyp-json-schema-04 (work in progress), January 2013. [ISO3166-1] "Country Codes", Chen, et al. Expires October 26, 2014 [Page 107] Internet-Draft paws-protocol April 2014 . [ITUT.X520.2008] International Telecommunication Union, "ITU-T Recommendation X.520: Information technology - Open Systems Interconnection - The Directory: Selected attribute types", November 2008, . [RFC6953] Mancuso, A., Probasco, S., and B. Patil, "Protocol to Access White-Space (PAWS) Databases: Use Cases and Requirements", RFC 6953, May 2013. [WGS-84] National Imagery and Mapping Agency, "Department of Defense World Geodetic System 1984, Its Definition and Relationships with Local Geodetic Systems, NIMA TR8350.2 Third Edition Amendment 1", January 2000, . Appendix A. Changes / Author Notes. To be removed before publication Changes from 11: o Change "regulatory rules" to "ruleset" o Change "regulatory specifics" to "ruleset specifics" o Change "regulatory-specific" to "ruleset-specific" o Change "regulatory domain" to "ruleset" where appropriate o Replace "depends on regulatory domain" to "optional" in tables o Add "optional" to "*other" in tables o Change "regulators" to "regulatory domains" o Change "REQUIRED" error name to "MISSING" o Changed the IANA instructions and added DE instructions to each section o Reformat and reorder IANA sections Changes from 10: o Ruleset Name change: ETSI-EN-301-598-1.0.9 and update reference to PDF o Add new ETSI parameter: etsiEnSimultaneousChannelOperationRestriction o Separate protocol requirements from regulatory requirements Changes from 09: Chen, et al. Expires October 26, 2014 [Page 108] Internet-Draft paws-protocol April 2014 o Updated format of the IANA section Changes from 08: o Fix JSON typos. o Added note that JSON schema is not intended to be formally validated o Finalize paws-iana-review@ietf.org as the email for updating the PAWS IANA registries o URLs to URIs o Typo fixes Changes from 07: o Propose ruleset ID name for ETSI: ETSI-EN-301-598-1.0.0-draft o Change TBD email address to paws-iana-review@ietf.org for proposing changes to the PAWS IANA registries o Moved discussion of required vCard properties to regulatory- specific sections o Fixed vCard examples for organization names: Use "fn" property, but set "kind" to "org". o Shorten parameter names: * freqHz -> hz * powerDbmPerBw -> dbm Changes from 06: o Multi-ruleset support: * Changed RulesetInfo to have single ruleset ID * Changed INIT_RESP to return a list of RulesetInfo parameters, rather than a single one * Changed REGISTRATION_RESP to return a list of RulesetInfo parameters to indicate the regulatory domains for which registration was accepted * Added SpectrumSpec (Section 5.9) parameter to represent available-spectrum specification for one regulatory domain, allowing AVAIL_SPECTRUM_RESP and AVAIL_SPECTRUM_BATCH_RESP to include answers for multiple regulatory domains * Changed GeoSpectrumSchedule to GeoSpectrumSpec (Section 5.15) for supporting batch responses to represent available spectrum for multiple regulatory domains at a location o To avoid ambiguity or redundant information, clarified that: * Event-time intervals within a single set of schedules MUST be disjoint * A single Spectrum element MUST cover the entire range of frequencies governed by a ruleset, rather than splitting them to present a "channelized" view o Add "ruleset" to Terminology section Chen, et al. Expires October 26, 2014 [Page 109] Internet-Draft paws-protocol April 2014 o Sync Terminology section with Use Case document o Add "masterDeviceDesc" to Device Validate request o Add "masterDeviceLocation" to the AVAIL_SPECTRUM requests and the SPECTRUM_NOTIFY message. Change "location" to be the location of the Slave Device, if the request is made by a Master Device on behalf of a Slave Device o Update vCard reference and example o Add jsonrpc 2.0 to all sample messages o Clarify that Listing Servers may be preconfigured in a device o Clarify meaning of maximum power levels vs bandwidth, including renaming parameter names: o * maxPowerDBm -> powerDbmPerBw * bandwidth -> resolutionBwHz o Explicitly allowed generic JSON-RPC error codes as possible codes. o Replace SHALL with MUST for consistency o Replace URI with URL for consistency o Reduce clutter in JSON encoding examples by removing string- concatenation characters o Changed "depends" to "depends on regulatory rules" in several places Changes from 05: o Remove requirement for JSON-RPC 1.0 o More typo fixes and clarifications Changes from 04: o Add "masterDeviceDesc" parameter to the available-spectrum requests to allow both Master and Slave device descriptors when the Master is making the request on behalf of a Slave. o Add "requestType" parameter to the available-spectrum requests to support requesting generic operating parameters for any Slave Device. o Add DbUpdateSpec as optional parameter to all response messages and to the error response to allow a Device to detect a database change at any stage of the control flow. o For the OUTSIDE_COVERAGE error, added ability to return a list of alternate databases o Explicitly allow JSON-RPC v2.0 and v1.0 encodings o Relaxed language that state, "MUST stop operation" to "MUST cease use of spectrum under rules for database-managed spectrum". I.e., the device may have other fallback strategies allowed by regulators. Changes from 03: Chen, et al. Expires October 26, 2014 [Page 110] Internet-Draft paws-protocol April 2014 o Expanded the Database Discovery mechanism to describe in more detail pre-configuration with URLs of databases and database- listing servers, including mechanisms for updating the configurations when things change * Add database-change field to Available Spectrum Response (Section 4.4.2) o Added fields that are anticipated to be needed by the ETSI harmonized standard for White Space Devices: * Added bandwidth constraints to the Available Spectrum Response (Section 4.4.2) * Updated Available Spectrum Response to return RulesetInfo, rather than just a ruleset identifier * Added optional device-manufacturer and device-model IDs to the DeviceDescriptor (Section 5.2) message. Also moved fccId from this message to the IANA section. * Expanded IANA (Section 9) sections o Clarified restrictions on the specification of the vertices of a Polygon. o Changed default confidence level to 95% for a point with uncertainty o Clarified how devices without absolute time source can use the timestamps in the response messages o Change method names to start with "spectrum.paws." prefix o Added maximum string lengths o Updated author contact info o More typo fixes Changes from 02: o Added timestamp to the AVAIL_SPECTRUM_RESP (Section 4.4.2) and AVAIL_SPECTRUM_BATCH_RESP (Section 4.4.4) data models to serve as a reference for the event times in the response. This was accidentally omitted (but was specified in their JSON encodings (Section 6)). o Fixed typos throughout the JSON encoding (Section 6) sections, typically adding missing commas. Changed from 01: o Added a description of message sequences to support multiple rulesets and multiple jurisdictions Section 3.1. o Modified DeviceDescriptor (Section 5.2) to add rulesetIds parameter o Modified RulesetInfo (Section 5.6), AvailableSpectrumResponse (Section 4.4.2) to add rulesetId parameter. o Add Extensibility (Section 8) section. Chen, et al. Expires October 26, 2014 [Page 111] Internet-Draft paws-protocol April 2014 o Filled in IANA (Section 9) section. o Removed blank Example Messages section Changes from 00: o Add JSON encoding o Adopt RFC5491 for GeoLocation o Adopt vCard for contact information o Add Response Code section and update text referencing the defined response codes o Change DeviceIdentifier to be DeviceDescriptor, allowing identifiers and device-characteristic fields to be included. Authors' Addresses Vincent Chen (editor) Google 1600 Amphitheatre Parkway Mountain View, CA 94043 US Email: vchen@google.com Subir Das Applied Communication Sciences 150 Mount Airy Road Basking Ridge, NJ 07920 U.S.A. Phone: Fax: Email: sdas at appcomsci dot com URI: Lei Zhu Huawei Phone: +86 13910157020 Fax: Email: lei.zhu@huawei.com URI: Chen, et al. Expires October 26, 2014 [Page 112] Internet-Draft paws-protocol April 2014 John Malyar iconectiv (formerly Telcordia Interconnection Solutions) 444 Hoes Lane/RRC 4E1106 Piscataway, NJ 08854 U.S.A. Phone: Fax: Email: jmalyar at iconectiv dot com URI: Peter J. McCann Huawei 400 Crossing Blvd, 2nd Floor Bridgewater, NJ 08807 USA Phone: +1 908 541 3563 Fax: Email: peter.mccann@huawei.com URI: Chen, et al. Expires October 26, 2014 [Page 113]