RFC 7545
Protocol to Access White-Space (PAWS) Databases
RFC 7545: Protocol to Access White-Space (PAWS) Databases ✨
Okay bestie, this is the PAWS spec, the protocol that lets devices ask a database which radio spectrum is free to use right now. 📡💖
Written by V. Chen (Ed.) at Google, with S. Das from Applied Communication Sciences, L. Zhu and P. McCann from Huawei, and J. Malyar from iconectiv. It's dated May 2015, it's a Standards Track document, and its ISSN is 2070-1721. The title block doesn't list anything it obsoletes or updates. 🌸
Abstract
Okay so, parts of the radio spectrum are licensed to specific users, but they're not always being used. When that spectrum is free and can be used without causing interference, it's called "white space." 🦋
Letting secondary users access that white space "unlocks" spectrum that already exists. That means it gets used more, which opens the door for innovation and better overall spectrum use. ✨
One way to manage this sharing is with databases that tell devices which spectrum is available. For devices and databases from different makers to work together, there has to be a standardized protocol that everyone defines and implements. This document defines that protocol, the "Protocol to Access White-Space (PAWS) Databases." 💅
Status of This Memo
This is an Internet Standards Track document. 🎀
It's an IETF product, so it represents the consensus of the IETF community. It went through public review and was approved for publication by the Internet Engineering Steering Group (IESG). For more on Internet Standards, check out Section 2 of RFC 5741. 🫶
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7545. 🔥
Copyright Notice
Copyright (c) 2015 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, which are at http://trustee.ietf.org/license-info and apply on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document. 📜
If you pull Code Components out of this document, they must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions. They're 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 . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Multi-ruleset Support . . . . . . . . . . . . . . . . . . 8
4. Protocol Functionalities . . . . . . . . . . . . . . . . . . 9
4.1. Database Discovery . . . . . . . . . . . . . . . . . . . 11
4.1.1. Preconfiguration . . . . . . . . . . . . . . . . . . 11
4.1.2. Configuration Update: Database URI Changes . . . . . 11
4.1.3. Error Handling . . . . . . . . . . . . . . . . . . . 12
4.2. PAWS Version . . . . . . . . . . . . . . . . . . . . . . 12
4.3. Initialization . . . . . . . . . . . . . . . . . . . . . 12
4.3.1. INIT_REQ . . . . . . . . . . . . . . . . . . . . . . 13
4.3.2. INIT_RESP . . . . . . . . . . . . . . . . . . . . . . 14
4.4. Device Registration . . . . . . . . . . . . . . . . . . . 15
4.4.1. REGISTRATION_REQ . . . . . . . . . . . . . . . . . . 16
4.4.2. REGISTRATION_RESP . . . . . . . . . . . . . . . . . . 17
4.5. Available Spectrum Query . . . . . . . . . . . . . . . . 18
4.5.1. AVAIL_SPECTRUM_REQ . . . . . . . . . . . . . . . . . 21
4.5.2. AVAIL_SPECTRUM_RESP . . . . . . . . . . . . . . . . . 23
4.5.3. AVAIL_SPECTRUM_BATCH_REQ . . . . . . . . . . . . . . 26
4.5.4. AVAIL_SPECTRUM_BATCH_RESP . . . . . . . . . . . . . . 28
4.5.5. SPECTRUM_USE_NOTIFY . . . . . . . . . . . . . . . . . 29
4.5.6. SPECTRUM_USE_RESP . . . . . . . . . . . . . . . . . . 31
4.6. Device Validation . . . . . . . . . . . . . . . . . . . . 31
4.6.1. DEV_VALID_REQ . . . . . . . . . . . . . . . . . . . . 32
4.6.2. DEV_VALID_RESP . . . . . . . . . . . . . . . . . . . 33
5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 34
5.1. GeoLocation . . . . . . . . . . . . . . . . . . . . . . . 34
5.2. DeviceDescriptor . . . . . . . . . . . . . . . . . . . . 37
5.3. AntennaCharacteristics . . . . . . . . . . . . . . . . . 38
5.4. DeviceCapabilities . . . . . . . . . . . . . . . . . . . 39
5.5. DeviceOwner . . . . . . . . . . . . . . . . . . . . . . . 39
5.6. RulesetInfo . . . . . . . . . . . . . . . . . . . . . . . 40
5.7. DbUpdateSpec . . . . . . . . . . . . . . . . . . . . . . 41
5.8. DatabaseSpec . . . . . . . . . . . . . . . . . . . . . . 42
5.9. SpectrumSpec . . . . . . . . . . . . . . . . . . . . . . 42
5.10. SpectrumSchedule . . . . . . . . . . . . . . . . . . . . 44
5.11. Spectrum . . . . . . . . . . . . . . . . . . . . . . . . 44
5.12. SpectrumProfile . . . . . . . . . . . . . . . . . . . . . 50
5.13. FrequencyRange . . . . . . . . . . . . . . . . . . . . . 51
5.14. EventTime . . . . . . . . . . . . . . . . . . . . . . . . 51
5.15. GeoSpectrumSpec . . . . . . . . . . . . . . . . . . . . . 52
5.16. DeviceValidity . . . . . . . . . . . . . . . . . . . . . 53
5.17. Error Element . . . . . . . . . . . . . . . . . . . . . . 53
5.17.1. OUTSIDE_COVERAGE Error . . . . . . . . . . . . . . . 55
5.17.2. DATABASE_CHANGE Error . . . . . . . . . . . . . . . 56
5.17.3. MISSING Error . . . . . . . . . . . . . . . . . . . 56
6. Message Encoding . . . . . . . . . . . . . . . . . . . . . . 57
6.1. JSON-RPC Binding . . . . . . . . . . . . . . . . . . . . 57
6.1.1. Method Names . . . . . . . . . . . . . . . . . . . . 59
6.1.2. JSON Encoding of Data Models . . . . . . . . . . . . 59
6.2. Example Encoding: spectrum.paws.init Method . . . . . . . 61
6.3. Example Encoding: spectrum.paws.getSpectrum Method . . . 62
6.4. Example Encoding: DeviceOwner vCard . . . . . . . . . . . 66
7. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . . . 66
8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 68
8.1. Defining Ruleset Identifiers . . . . . . . . . . . . . . 68
8.2. Defining New Message Parameters . . . . . . . . . . . . . 69
8.3. Defining Additional Error Codes . . . . . . . . . . . . . 69
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69
9.1. PAWS Ruleset ID Registry . . . . . . . . . . . . . . . . 70
9.1.1. Registration Template . . . . . . . . . . . . . . . . 70
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 72
9.2. PAWS Parameters Registry . . . . . . . . . . . . . . . . 78
9.2.1. Registration Template . . . . . . . . . . . . . . . . 78
9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 78
9.3. PAWS Error Code Registry . . . . . . . . . . . . . . . . 80
9.3.1. Registration Template . . . . . . . . . . . . . . . . 81
9.3.2. Initial Registry Contents . . . . . . . . . . . . . . 81
10. Security Considerations . . . . . . . . . . . . . . . . . . . 81
10.1. Assurance of Proper Database . . . . . . . . . . . . . . 83
10.2. Protection against Modification . . . . . . . . . . . . 84
10.3. Protection against Eavesdropping . . . . . . . . . . . . 84
10.4. Client Authentication Considerations . . . . . . . . . . 84
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 85
11.1. Normative References . . . . . . . . . . . . . . . . . . 85
11.2. Informative References . . . . . . . . . . . . . . . . . 86
Appendix A. Database Listing Server Support . . . . . . . . . . 88
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 89
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 901. Introduction ✨
This section is the high-level intro, bestie. If you want use cases, requirements, and more background, you should definitely read "Protocol to Access White-Space (PAWS) Databases: Use Cases and Requirements" [RFC6953]. 📚
A geospatial database can track available spectrum, following the rules of one or more regulatory domains, and share that info with devices. This approach moves the hard part of spectrum-policy conformance out of the device and into the database 🧚 It also makes policy changes easier to roll out, since you only update a handful of databases instead of tons of devices. 💅 It opens the door for spectrum-management innovations that can factor in all kinds of things, including user location and time. Later on, it could also include stuff like user priority, signal type and power, spectrum supply and demand, payment or micro-auction bidding, and more. 🌈
Now, here's the serious part. The database records and updates info needed to protect primary users. That might include a fixed transmitter's call sign, its geolocation, antenna height, power, and periods of operation. 🛡️ The rules the database has to follow, including its schedule for getting and updating protection info, its protection rules, and what it reports to devices, all depend on the regulatory domain. Those differences should be handled by each database and hidden from devices as much as possible. 🫶
This specification defines an extensible protocol, built on top of HTTP and TLS. A device with geolocation capability uses it to get available spectrum from a geospatial database. It lets a device operate in any regulatory domain that uses this protocol. 🦋
2. Conventions and Terminology 🎀
2.1. Conventions Used in This Document
Okay, the key words are the important part here, so pay attention 🙈 In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 💜
2.2. Terminology
okay bestie, let's get into the glossary 💅✨ these terms are the vocab for the whole spec, so pay attention 🫶
- Database or Spectrum Database: a Database is an entity that contains current info about available spectrum at a given location and time, plus other types of info related to spectrum availability and usage 🗺️
- Device ID: an identifier for a device 🪪
- EIRP: Effective Isotropically Radiated Power ⚡
- ETSI: European Telecommunications Standards Institute (
http://www.etsi.org) 🇪🇺 - FCC: The U.S. Federal Communications Commission (
http://www.fcc.gov) 🇺🇸 - 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 get available spectrum info 📡
- 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 PAWS is agnostic as to how a regulatory domain is constructed 🏛️ (PAWS doesn't pick sides, it's giving neutral queen energy)
- Ruleset: a ruleset represents a set of rules that governs the operation of white-space devices and Spectrum Databases. a regulatory authority can define its own set of rules or adopt an existing ruleset. when a Database or device is said to "support a ruleset", it means that it contains out-of-band knowledge of the rules and that its hardware and software implementations conform to those rules 📜🔥
- Ruleset Identifier: a ruleset can be identified by an IANA-registered identifier (see PAWS Ruleset ID Registry (Section 9.1)). when a Database or device indicates it supports a ruleset identifier, it means that it conforms to the rules associated with that identifier. a regulatory authority can define and register its own ruleset identifiers, or it can use a previously registered identifier if it adopts an existing ruleset 🏷️
- Slave Device: a device that queries the Database through a master device 🦋
3. Protocol Overview
A Master Device uses PAWS to obtain a schedule of available spectrum at its location. the security needed to keep the device's location accurate, private, and confidential 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 goes like this 👀 (see "Protocol Functionalities" (Section 4) and "Protocol Parameters" (Section 5) for the deets):
- The Master Device obtains (statically or dynamically) the URI for a Database appropriate for its location, to which to send subsequent PAWS messages.
- The Master Device establishes an HTTPS session with the Database.
- The Master Device optionally sends an initialization message to the Database to exchange capabilities.
- If the Database receives an initialization message, it responds with an initialization-response message in the body of the HTTP response.
- The Database may require the Master Device to be registered before providing service.
- The Master Device sends an available-spectrum request message to the Database. the message may be on behalf of a Slave Device that made a request to the Master Device.
- If the Master Device is making a request on behalf of a Slave Device, the Master Device may verify with the Database that the Slave Device is permitted to operate.
- The Database responds with an available-spectrum response message in the body of the HTTP response.
- The Master Device may send a spectrum-usage notification message to the Database. the notification is purely informational; it tells the Database what spectrum the Master Device intends to use and is not a request to the Database for permission to use that spectrum. some Databases may require spectrum-usage notification.
- If the Database receives a spectrum-usage notification message, it responds by sending the Master Device a spectrum-usage acknowledgement message. since the notification is purely informational, the Master Device does not need to process the database response 🙌
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, PAWS supports the following sequence of operations for each request by the Master Device 🧩:
- 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.
- 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.
- If required parameters are missing from the request, the Database responds with an error and a list of names of the missing parameters.
- The Master Device makes the request again, adding the missing parameter values.
- The Database responds to the request, including the identifier of the applicable ruleset.
- The Master Device uses the indicated ruleset to determine how to interpret the database response.
NOTE: some regulatory domains specify sets of requirements for device behavior that may be complex and not easily parameterized. the ruleset-id parameter gives the Database a way to tell the Master Device which ruleset applies, so devices with out-of-band knowledge of the particular regulatory domain requirements can satisfy them without the device-side behavior having to be spelled out inside the protocol 🤓. ruleset identifiers will normally contain the name of the regulatory body that established the rules and version info, such as FccTvBandWhiteSpace-2010 💜
by separating the regulatory "authority" from the "ruleset-id", the protocol can support multiple regulatory authorities that use the same device-side ruleset. it also lets a single authority define multiple rulesets. big brain stuff 🧠✨
4. Protocol Functionalities
PAWS has several components 🧃. as noted below, some regulatory domains or database implementations may mandate the use of a component, even when PAWS itself doesn't mandate it.
- Database Discovery (Section 4.1) is a required component for the Master Device.
- Initialization (Section 4.3) is a required component for the Database. its use lets the Master Device figure out the info it needs that hasn't been preconfigured 🔧
- Device Registration (Section 4.4) is an optional component for the Database. it can be implemented as a separate component or as part of the Available Spectrum Query (Section 4.5) component. the Master Device uses it when the Database requires it. some regulators require device registration for only specific device types, such as higher-power fixed (as opposed to mobile) devices, so they can contact the operators to sort out any interference issues 📞
- Available Spectrum Query (Section 4.5) is a required component for the Master Device and the Database 🔍
- Spectrum Use Notify (Section 4.5.5) is an optional component for the Master Device and the Database. when it is required, the Database tells the Master Device about it via its response to the Available Spectrum Query (Section 4.5) 📣
- Device Validation (Section 4.6) as a separate component is optional for the Master Device and Database. when the Database implements it, the Master Device can validate Slave Devices without having to use the full Available Spectrum Query 🪪✅
this section describes the protocol components and their messages. "Protocol Parameters" (Section 5) has a more thorough breakdown of the parameters that make up the PAWS request and response messages. "Message Encoding" (Section 6) has examples of message encodings. "HTTPS Binding" (Section 7) describes the use of HTTPS ("HTTP Over TLS" [RFC2818]) for transferring PAWS messages and optional device authentication 🎀
the parameter tables in this section and "Protocol Parameters" (Section 5) are for reference. they list the name of each parameter, its data type, and whether the parameter must be present for the protocol transaction in question. the diagrams are loosely based on the Unified Modeling Language (UML), and the data types are defined either in "Protocol Parameters" (Section 5) or are one of the following primitive or structured types 📊:
- string: a string, as defined by JSON [RFC7159], restricted to the UTF-8 encoding.
- int: a number, as defined by JSON [RFC7159], without a fractional or exponent part.
- float: a number, as defined by JSON [RFC7159].
- boolean: a boolean, as defined by JSON [RFC7159].
- list: a structured type that represents a list of elements, as defined by JSON [RFC7159] array type. all elements of the list are of the same data type, which is indicated in its diagram and description. the diagram notation and description may include additional constraints, such as minimum or maximum number of elements 📝
also:
- all parameter names are case sensitive. unless stated otherwise, all string values are case sensitive 🔠
- all timestamps are in UTC and are expressed using exactly the form
YYYY-MM-DDThh:mm:ssZ, as defined by "Date and Time on the Internet: Timestamps" [RFC3339] ⏰
in some cases, specific rulesets may place additional requirements on message parameters. these additional requirements will be documented in the IANA PAWS Ruleset ID Registry (Section 9.1). when a request message sent to the Database has missing parameters, whether they are required by PAWS or by the applicable ruleset, the Database returns the MISSING error (see Section 5.17.3), along with data indicating the missing parameters 🚨
4.1. Database Discovery
4.1.1. Preconfiguration
the Master Device can be provisioned statically (preconfigured) 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 preconfigured in the device 🛠️
Listing Server Support: as an alternative to preconfiguring devices with a list of certified Databases, some regulatory domains support preconfiguring devices with the URI of a certified listing server. devices can connect to it to get the list of certified Databases. see "Database Listing Server Support" (Appendix A) for further info 💜✨
4.1.2. Configuration Update: Database URI Changes 🦋
Okay bestie, databases can change their URIs, and devices have to keep up 💅 To adapt to changes in the list of certified or approved Databases, the device needs to update its preconfigured list of Databases. ✨
A Database MAY change its URI, but before it does, it MUST announce the upcoming change by including the URI of one or more alternate Databases using DbUpdateSpec (Section 5.7) in its responses to devices. 📣 The Database MUST keep replying with DbUpdateSpec for a minimum of 2 weeks before it disables the old URI. ⏳ A device will update its preconfigured entry for the Database that sent the DbUpdateSpec by replacing that entry with the alternate Databases listed in the DbUpdateSpec. The list of alternate Databases does not affect any other entries, so no drama there 🙅♀️ Also, the ordering of Databases in the list does not imply any preference, and it does not need to stay the same for every request. Ordering is not a vibe check 🫶
The device SHOULD detect infinite redirection loops. 🔁 If a suitable Database cannot be contacted, the device MUST treat this as equivalent to a response indicating no available spectrum. 🙃
This database-change mechanism is used, for example, before a Database ceases operation. It is not intended to be used for dynamic load balancing, so please don't try to turn it into a load balancer 💀
4.1.3. Error Handling 🚨
The device SHOULD select another Database from its list of preconfigured Databases if:
- The selected Database is unreachable or does not respond.
- The selected Database returns an
UNSUPPORTEDerror (see "Error Codes" (Section 5.17)), which indicates the Database does not support the device (based on its device type, model, etc.) or supports none of the rulesets specified in the request.
If a suitable Database cannot be contacted, the device MUST treat this as equivalent to a response indicating no available spectrum. 🫠 Now, if the device had previously contacted a Database to get available spectrum but then can't reach a suitable Database, the spectrum it's currently using can keep being used for as long as the spectrum data is valid. ⏰ After that period, though, the device will no longer have valid spectrum to use, and that's the end of that era 😭 Some regulatory domains may have specific rules about how long spectrum data remains valid in these cases, so check the local rules too 📜
4.2. PAWS Version 🎀
PAWS version uses a "<major>.<minor>" numbering scheme to indicate versions of the protocol. The protocol versioning policy is meant to let the device or Database signal the format of a message and its understanding of PAWS functionality defined by that version. 🧠 No change is made to the version string for the addition of message components that only add to extensible parameter values. 🌸
The <minor> number is incremented when the changes made to the protocol add functionalities (methods) but do not change the existing functionalities. ✨ The <major> number is incremented when incompatible changes are made to existing functionality. 💥
The current PAWS version is "1.0". 🫶
4.3. Initialization 🌈
A Master Device SHOULD use the initialization procedure to exchange capability information with the Database whenever the Master Device powers up or starts communicating with the Database. 🔌 The initialization response tells the Master Device about specific parameterized-rule values for each supported ruleset, like threshold distances and time periods. Once those limits are passed, the device must update its available-spectrum data (see "RuleSetInfo" (Section 5.6)). ⏱️
When parameterized-rule values are not preconfigured for the applicable ruleset at the specified location, a Master Device MUST use the initialization procedure. 🙏
It is important to note that, when parameterized-rule values are preconfigured in a Master Device, they are preconfigured on a per-ruleset basis. In other words, values preconfigured for one ruleset are not applicable to any other ruleset. 🚫 Keep your rulesets separate, babe 🗂️
For database implementations that require it, the initialization message also lets extra database-specific or ruleset-specific handshake parameters be communicated before available-spectrum requests are allowed. 🤝
The Initialization request procedure is depicted in Figure 1. 👀
- INIT_REQ (Section 4.3.1) is the initialization request message
- INIT_RESP (Section 4.3.2) is the initialization response message
+---------------+ +-------------------+
| Master Device | | Spectrum Database |
+---------------+ +-------------------+
| |
| INIT_REQ |
|-------------------->|
| |
| INIT_RESP |
|<--------------------|
| |
Figure 14.3.1. INIT_REQ 📨
The initialization request message lets the Master Device start a capability exchange 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 device descriptor does not contain any ruleset IDs, the Master Device is asking the Database to return a RulesetInfo (Section 5.6) list that specifies the rulesets it supports at the specified location. 🗺️location: The GeoLocation (Section 5.1) of the device is REQUIRED. 📍 If the location is outside all regulatory domains supported by the Database, the Database MUST respond with anOUTSIDE_COVERAGEerror (see Table 1). 🌍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 keep its initialization logic simple, a Master Device that supports multiple Databases and rulesets can include the union of all required parameters for all of its supported rulesets. 🧩 Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. 📚
4.3.2. INIT_RESP 🎁
The initialization response message communicates database parameters to the requesting device. This response is only returned when there is at least one ruleset. 🙌 Otherwise, the Database returns an error response, as described in INIT_REQ (Section 4.3.1). ❌
+---------------------------------------+
|INIT_RESP |
+----------------------------+----------+ 1..* +-------------+
|rulesetInfos:list | REQUIRED |------->| RulesetInfo |
|databaseChange:DbUpdateSpec | OPTIONAL | +-------------+
|.......................................|
|*other:any | OPTIONAL |
+----------------------------+----------+Parameters:
rulesetInfos: A RulesetInfo (Section 5.6) list MUST be included in the response. 📋 Each RulesetInfo corresponds to a ruleset supported by the Database and is applicable to the location specified in the INIT_REQ (Section 4.3.1) message. 📍- If the device included a list of ruleset IDs in the DeviceDescriptor of its INIT_REQ message, each RulesetInfo in the response MUST match one of the specified ruleset IDs. 🎯
- If the DeviceDescriptor did not contain any ruleset IDs, the Database SHOULD include in the
rulesetInfoslist a RulesetInfo for each ruleset it supports at the specified location. 🫧 - If the Database does not support the device or supports none of the rulesets specified in the DeviceDescriptor, it MUST instead return an error with the
UNSUPPORTEDcode (see Table 1) in the error response. 😬
databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) to notify the Master Device of a change to the database URI, providing one or more alternate database URIs. 🔄 The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec. 🦋other: The Database MAY include additional handshake parameters in the INIT_RESP (Section 4.3.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.4. Device Registration 📝
Some rulesets require a Master Device to send its registration information to the Database so certain operational parameters can be established. 🗂️ 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 (see FCC CFR47-15H [FCC-CFR47-15H]). 📡
The Database MAY implement device registration as a separate Device Registration request, or as part of the available-spectrum request. 🤔 If the Database does not implement a separate Device Registration request, it MUST return an error with the UNIMPLEMENTED code (see Table 1) in the error-response message. 🙅♀️
The Device Registration request procedure is depicted in Figure 2. 👑
- REGISTRATION_REQ (Section 4.4.1) is the device-registration request message
- REGISTRATION_RESP (Section 4.4.2) is the device-registration response message
+---------------+ +-------------------+
| Master Device | | Spectrum Database |
+---------------+ +-------------------+
| |
| REGISTRATION_REQ |
|------------------------>|
| |
| REGISTRATION_RESP |
|<------------------------|
| |
Figure 24.4.1. REGISTRATION_REQ ✨
okay so the registration request is basically the device going "hi bestie, I'm here, let me in!" 💖 It carries the required registration parameters. Some rulesets want extra stuff too, so anything marked OPTIONAL might end up being needed depending on the ruleset 🙈
+-------------------------------------------+
|REGISTRATION_REQ |
+-------------------------------+-----------+
|deviceDesc:DeviceDescriptor | REQUIRED |
|location:GeoLocation | REQUIRED |
|deviceOwner:DeviceOwner | OPTIONAL |
|antenna:AntennaCharacteristics | OPTIONAL |
|...........................................|
|*other:any | OPTIONAL |
+-------------------------------+-----------+Here's the breakdown of each parameter 🎀
deviceDesc: the DeviceDescriptor (Section 5.2) for the Master Device is REQUIRED. The ruleset IDs inside the DeviceDescriptor tell the Database which rulesets the device wants to register for. Main character energy 👑location: the GeoLocation (Section 5.1) for the device is REQUIRED. More precisely, it's the spot where the device plans to operate 📍 If that location is outside every regulatory domain the Database supports, the Database MUST respond with anOUTSIDE_COVERAGEerror (see Table 1). No cap, that's a hard no 💀deviceOwner: the DeviceOwner (Section 5.5) info is OPTIONAL. Some rulesets may ask for deviceOwner info under certain conditions, so check the PAWS Ruleset ID Registry (Section 9.1) for the ruleset-specific requirements 🧚antenna: the AntennaCharacteristics (Section 5.3) is OPTIONAL. 🦋other: rulesets and database implementations may need additional registration parameters. To keep its registration logic simple, the Master Device MAY send a union of the registration information required by all of its supported rulesets 💅 The Database MUST ignore all parameters it does not understand. Lowkey iconic of the Database to just vibe past what it doesn't know 🫶 For possible extra parameters, check the PAWS Parameters Registry (Section 9.2).
4.4.2. REGISTRATION_RESP ✨
The registration response is the Database's "yep, you're in!" 🌸 It acknowledges a successful registration by including a RulesetInfo message for each ruleset where the registration was accepted. If the Database accepts the registration for none of the requested rulesets, it MUST return the NOT_REGISTERED error (see "Error Codes" (Section 5.17)). Rough day for that device 😭
+---------------------------------------+
|REGISTRATION_RESP |
+----------------------------+----------+ 1..* +-------------+
|rulesetInfos:list | REQUIRED |------->| RulesetInfo |
|databaseChange:DbUpdateSpec | OPTIONAL | +-------------+
|............................|..........|
|*other:any | OPTIONAL |
+----------------------------+----------+Here's the parameter tea ☕
rulesetInfos: a RulesetInfo (Section 5.6) list MUST be included in the response. Each entry matches a ruleset where the registration was accepted. The list MUST contain at least one entry. ✨
Every RulesetInfo in the response MUST match one of the ruleset IDs listed in the DeviceDescriptor of the REGISTRATION_REQ. No random IDs allowed, that's giving chaos 🌀
If the Database doesn't support the device, or supports none of the rulesets in the DeviceDescriptor, it MUST instead return an error with the UNSUPPORTED code (see Table 1) in the error response. 💔
databaseChange: the Database MAY include a DbUpdateSpec (Section 5.7) to tell the Master Device about a change to the database URI, giving one or more alternate database URIs. The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec. Update your contacts, bestie 📱other: Database implementations MAY return additional parameters in the registration response. The Master Device MUST ignore any parameters it does not understand. Same energy as before, mutual respect 🫶 For possible additional parameters, consult the PAWS Parameters Registry (Section 9.2).
4.5. Available Spectrum Query 🦋
okay this is the main event, the spectrum shopping trip 🛍️ To get the available spectrum from the Database, a Master Device sends a request that contains its geolocation and any parameters the ruleset needs (like device identifier, capabilities, and characteristics). The Database sends back a response that says which frequencies are available, what permissible operating power levels apply, and a schedule of when they're available. Schedule AND power levels, iconic 💜
The Available Spectrum Query procedure is shown in Figure 3 🎀
AVAIL_SPECTRUM_REQ(Section 4.5.1) is the available-spectrum request message.AVAIL_SPECTRUM_RESP(Section 4.5.2) is the available-spectrum response message.AVAIL_SPECTRUM_BATCH_REQ(Section 4.5.3) is an OPTIONAL batch version of the available-spectrum request message. It lets you specify multiple locations in one request, which is very efficient bestie behavior 🧚AVAIL_SPECTRUM_BATCH_RESP(Section 4.5.4) is the response message for the batch version of the request. It contains available spectrum for each location in the request.SPECTRUM_USE_NOTIFY(Section 4.5.5) is the spectrum-usage notification message.SPECTRUM_USE_RESP(Section 4.5.6) is the spectrum-usage acknowledgment message.
+---------------+ +-------------------+
| 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 3Here's the step-by-step vibe check ✨
- First, the Master Device sends an available-spectrum request message to the Database. Send it, bestie 📨
- The Database MUST respond with an error using the
NOT_REGISTEREDcode (see Table 1) if all of these are true:- registration information is required, and
- the request does not include registration information, and
- the device has not previously registered with the Database
Not registered, no spectrum for you 🚫
- If the location in the request is outside the regulatory domain the Database supports, the Database MUST respond with an
OUTSIDE_COVERAGEerror (see Table 1). If some, but not all, locations in a batch request are outside that domain, the Database MUST return anOKresponse with available spectrum for only the valid locations. Otherwise, if all locations in a batch request are outside the regulatory domain, the Database MUST respond with anOUTSIDE_COVERAGEerror. Partial slay is still slay 💅 - The Database MAY perform other validation of the request (e.g., checking for missing required parameters or 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
MISSINGerror (see Table 1) and SHOULD include a list of the missing parameters. Checking for the vibes 🔍 - If the request is valid, the Database responds with an available-spectrum response message. If the ruleset requires devices to report anticipated spectrum usage, the Database will indicate that in the response message. 🌈
- If the available-spectrum response indicates the Master Device must send a spectrum-usage notification message, the Master Device sends that notification to the Database. Even when the Database doesn't require it, the Master Device MAY send a notification message. Extra credit, the good kind 🍓
- If the Database receives a spectrum-usage notification message, it MUST send a spectrum-usage acknowledgment message to the Master Device. Acknowledged, periodt 💖
The procedure for a Master Device to ask for available spectrum on behalf of a Slave Device is similar, except the process is started by the Slave Device. The device identifier, capabilities, and characteristics in the AVAIL_SPECTRUM_REQ message MUST be those of the Slave Device, and:
- The
masterDeviceLocationfield, which specifies the location of the Master Device, is REQUIRED. - The
locationfield, which specifies the location of the Slave Device, is OPTIONAL, since the Slave Device may not have location-sensing capabilities. Not everyone has GPS, and that's valid 🫶
Although the communication and protocol between the Slave Device and Master Device are outside the scope of this document (shown as dotted lines), the expected message sequence is in Figure 4 🧚
+------------+ +---------------+ +-------------------+
|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 44.5.1. AVAIL_SPECTRUM_REQ ✨
Okay bestie, the request message for the Available Spectrum Query MUST include a geolocation 📍 No skipping this one! Rulesets get to decide whether it has to be the device's current spot or whether an anticipated location is fine. Some rulesets might also need a parameter that's marked as optional, so keep an eye out 👀
+----------------------------------------------------+
|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 | see description |
|requestType:string | OPTIONAL |
|..................................|.................|
|*other:any | OPTIONAL |
+----------------------------------+-----------------+Here's the breakdown of the parameters 💅
deviceDesc: this is the DeviceDescriptor (Section 5.2) for whichever device is asking for spectrum. If the Master Device is asking for itself, the descriptor is its own and it is REQUIRED 🫶 If the request is made for a Slave Device, the descriptor is the Slave's and it is REQUIRED only whenrequestTypeis not specified.deviceDescmay be OPTIONAL for some values ofrequestType, so check the ruleset.location: this is the GeoLocation (Section 5.1) of the device asking for spectrum. More precisely, it's where the device plans to operate ✨ If the Master Device is asking for itself, the location is its own and it is REQUIRED. If the Master Device is asking for a Slave Device, the location is the Slave's and it is OPTIONAL (see alsomasterDeviceLocation). The location can be an anticipated position so mobile devices can use it, but whether that's allowed depends on the ruleset. If the location describes a region instead of a point, the Database MAY return an error with the UNIMPLEMENTED code (see Table 1) if it doesn't support query by region 🙈
NOTE: Technically this is the location of the radiation center of the device's antenna, but that detail may only matter for fixed devices. Lowkey a fun fact 🤓
owner: the DeviceOwner (Section 5.5) information MAY be included to register the device with the Database. This lets the device register and get its spectrum-availability info in one single request, which is so efficient 🦋 Some rulesets mandate registration for specific device types.antenna: the AntennaCharacteristics (Section 5.3) is OPTIONAL, so it's up to you 💖capabilities: the Master Device MAY include its DeviceCapabilities (Section 5.4) to narrow the available-spectrum response down to spectrum that works with its capabilities. The Database SHOULD NOT return spectrum that isn't compatible with the capabilities you specified 🎀masterDeviceDesc: when the Master Device asks on behalf of a Slave Device, the Master Device MAY give its own descriptor too 🧚masterDeviceLocation: when the Master Device asks on behalf of a Slave Device, the Master Device MUST provide its own GeoLocation (Section 5.1). This one's non-negotiable 💀requestType: this one is OPTIONAL. It can tweak the request, but what it actually does depends on the ruleset. For example, it can ask for generic Slave Device parameters so you don't have to name a specific device descriptor. IfrequestTypeis missing, the request is about one specific device (Master or Slave), sodeviceDescis REQUIRED. The value can be at most 64 octets long. For the specifics, check the Initial Registry Contents (Section 9.1.2) for the Ruleset ID Registry 🌸other: rulesets and database implementations might need extra request parameters. The Database MUST ignore all parameters it doesn't understand, so no drama if it sees something unfamiliar 🍓 For possible additional parameters, check the PAWS Parameters Registry (Section 9.2).
4.5.2. AVAIL_SPECTRUM_RESP ✨
The response to the Available Spectrum Query has one or more SpectrumSpec (Section 5.9) elements, one for each ruleset supported at the location from the matching AVAIL_SPECTRUM_REQ (Section 4.5.1) message 🌈 Each SpectrumSpec holds a list of one or more spectrum schedules, which show the permissible power levels over time:
- Each spectrum schedule gives the permissible power level for a duration set by a start time and a stop time. The power levels are the permissible EIRP over a resolution bandwidth 📊
- Within each list of schedules, the event-time intervals MUST be disjoint and MUST be sorted in increasing time. No overlapping, no shuffling, periodt 💅
- A gap in the time schedule means no spectrum is available for that interval. So a gap is basically a "nope, not right now" 🙅♀️
Picture a Database that gives you a schedule of available spectrum for the next 24 hours. If spectrum availability changes at different times of day, the response includes a list of schedules, with each transition marking a change in what's available ⏰ A device might pick its spectrum in different ways, for example:
- Always use the frequencies that permit the highest power
- Use the frequencies that are available for the longest period of time.
- Just use the first set of frequencies that matches its needs.
+---------------------------------------+
|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 |
+--------------------+----------+Here's what each parameter is about 🦋
timestamp: the response timestamp is in UTC, in the form YYYY-MM-DDThh:mm:ssZ, as defined by "Date and Time on the Internet: Timestamps" [RFC3339]. The device can use it as a reference point for the start and stop times in the spectrum schedules ⏱️deviceDesc: the Database MUST include the DeviceDescriptor (Section 5.2) that came in the AVAIL_SPECTRUM_REQ message. It's giving "I see you" energy 👀spectrumSpecs: the SpectrumSpec (Section 5.9) list MUST include at least one entry. Each entry has the schedules of available spectrum for one ruleset. The Database MAY return more than one SpectrumSpec to cover available spectrum for multiple rulesets at the specified location 🌈databaseChange: the Database MAY include a DbUpdateSpec (Section 5.7) to tell the device about a change to the database URI, with one or more alternate database URIs. The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec 🔄other: Database implementations MAY return additional parameters in the response. The device MUST ignore any parameters it doesn't understand. For possible extra parameters, and any requirements they put on the device, check the PAWS Parameters Registry (Section 9.2) 🧚
4.5.2.1. Update Requirements
When the stop time in the schedule has been reached, the device:
- MUST obtain a new spectrum-availability schedule, either by using the next one in the list (if one was provided) or by making another Available Spectrum Query (Section 4.5). No stale schedules, bestie ⏳
- If the device can't reach the Database to get a new schedule, it MUST treat this the same as a response with no available spectrum 🫠
Some rulesets also mandate that a device must get a new spectrum-availability schedule if it moves beyond a threshold distance (set by the ruleset) from its actual location and from all the anticipated locations it reported in previous AVAIL_SPECTRUM_REQ or AVAIL_SPECTRUM_BATCH_REQ messages. See "maxLocationChange" in RulesetInfo (Section 5.6) for details 🗺️ If the device can't reach the Database to get a new schedule, it MUST treat this the same as a response with no available spectrum.
NOTE: The ruleset decides what the device has to do when spectrum is no longer available 📜 It also decides whether a device may request and use spectrum at anticipated locations beyond the threshold distance from its current location. The ruleset is the boss here 👑
4.5.3. AVAIL_SPECTRUM_BATCH_REQ ✨
Okay bestie, so the Database MAY implement the batch request, which lets you send a bunch of locations in one go 🧳. A portable Master Device is the obvious use case: it can ask for spectrum at a whole sequence of places it expects to be, all in a single request 🗺️✨. The Database treats each location like its own separate request and gives back results that match multiple individual AVAIL_SPECTRUM_REQ (Section 4.5.1) messages, except they come back bundled up in a batched response (Section 4.5.4) 🎁. The batch request for this query MUST include at least one GeoLocation (Section 5.1) 💅. If the Database doesn't do batch requests, it MUST return an UNIMPLEMENTED error (see Table 1) 💀.
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 | see description | |
|requestType:string | OPTIONAL | |
+.................................+.................+ |
|*other:any | OPTIONAL | |
+---------------------------------+-----------------+ |
|
1..* V
+-------------+
| GeoLocation |
+-------------+Parameters:
deviceDesc: This is the DeviceDescriptor (Section 5.2) for whichever device is asking for spectrum 📱. If a Master Device is asking for itself, it's the Master's descriptor and it is REQUIRED 🙌. If it's asking on behalf of a Slave Device, it's the Slave's descriptor, and it is REQUIRED ifrequestTypeisn't specified 🤝. ThedeviceDescparameter may be OPTIONAL for some values ofrequestType🌸.locations: The GeoLocation (Section 5.1) list for the device is REQUIRED 📍. This lets the device share its real location plus any anticipated ones 🗺️. At least one location MUST be included 💖. There's no upper limit on how many locations you can send, but the Database MAY restrict how many it supports, so it can reply with fewer locations than you asked for 🙃. If the locations describe regions instead of points, the Database MAY return an error with the UNIMPLEMENTED code (see Table 1) if it doesn't do query by region 🌍. If a Master Device is asking for itself, the locations are the Master's own. If it's asking for a Slave Device, the locations are the Slave's (see alsomasterDeviceLocation) 🫶.owner: The DeviceOwner (Section 5.5) info MAY be included to register the device with the Database 📝. That means the device can register and check spectrum availability in one request, which is so efficient 🧚. 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) so the response only shows spectrum that works with what it can do 🎯. The Database SHOULD NOT return spectrum that isn't compatible with the capabilities you listed 🙅♀️.masterDeviceDesc: When a Master Device is asking on behalf of a Slave Device, the Master Device MAY provide its own descriptor 🎀.masterDeviceLocation: When a Master Device is asking on behalf of a Slave Device, the Master Device MUST provide its own GeoLocation (Section 5.1) 📌.requestType: This is an OPTIONAL parameter that can tweak the request, but what it does depends on the applicable ruleset 🔧. For example, you can use it to ask for generic Slave Device parameters without naming a specific device descriptor 🧁. WhenrequestTypeis missing, the request is for one specific device (Master or Slave), sodeviceDescis REQUIRED 🫠. The maximum length is 64 octets 📏. Check the ruleset specifics in the Initial Registry Contents (Section 9.1.2) for the Ruleset ID Registry 📚.other: Rulesets and database implementations may need extra request parameters 🧩. The Database MUST ignore all parameters it doesn't understand 🙈. Check the PAWS Parameters Registry (Section 9.2) for possible additional parameters 🔍.
4.5.4. AVAIL_SPECTRUM_BATCH_RESP 🎀
The batch response is the reply to the batch Available Spectrum Query, and it holds a schedule of available spectrum for the device at multiple locations 📅.
+---------------------------------------+
|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: This is the time of the response, in the form YYYY-MM-DDThh:mm:ssZ, as defined by "Date and Time on the Internet: Timestamps" [RFC3339] ⏰. The device can use it as a reference point for the start and stop times in the spectrum schedules 🕰️.deviceDesc: The Database MUST include the DeviceDescriptor (Section 5.2) that was specified in the AVAIL_SPECTRUM_BATCH_REQ message 🪪.geoSpectrumSpecs: This list (Section 5.15) is REQUIRED, although it MAY be empty if no spectrum is available 🫥. For each location, the Database MAY return one or more SpectrumSpecs (Section 5.9) to show the available spectrum for one or more rulesets 🌈. The Database MAY return available spectrum for fewer locations than you requested 🙃. The order of the entries doesn't matter, but the device MUST use thelocationvalue in each GeoSpectrumSpec entry to match available spectrum to a location 🧭.databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) to let the device know the database URI changed, with one or more alternate database URIs 🔄. The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec 💌.other: Database implementations MAY return extra parameters in the response 🎁. Check the PAWS Parameters Registry (Section 9.2) for possible additional parameters and any requirements they put on the device 📖.
See "Update Requirements" (Section 4.5.2.1) for when the device must update its available spectrum data ⏳✨.
4.5.5. SPECTRUM_USE_NOTIFY 📣
The spectrum-use notification tells everyone which spectrum the device expects to use 🦋.
+---------------------------------------------------+
|SPECTRUM_USE_NOTIFY |
+---------------------------------+-----------------+
|deviceDesc:DeviceDescriptor | REQUIRED |
|location:GeoLocation | see description |
|masterDeviceDesc:DeviceDescriptor| OPTIONAL |
|masterDeviceLocation:GeoLocation | see description |
|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: This is the GeoLocation (Section 5.1) for the device 📍. If a Master Device is sending the notification for itself, the location is the Master's and it is REQUIRED 💪. If a Master Device is sending it on behalf of a Slave Device, the location is the Slave's and it is OPTIONAL, but some rulesets may require it 🫶.spectra: This Spectrum (Section 5.11) list is REQUIRED and says which spectrum the device expects to use, including the frequency and power profiles 🌊. The list MAY be empty if the device decides not to use any spectrum 🫧. For consistency,resolutionBwHzMUST match one of the Spectrum (Section 5.11) elements in the corresponding AVAIL_SPECTRUM_RESP message 🔁. The maximum power levels in the Spectrum element MUST be expressed as power (EIRP) over the specifiedresolutionBwHzvalue 💡. The actual bandwidth used (computed from the start and stop frequencies) MAY differ fromresolutionBwHz🎚️. For example, if the ruleset expresses maximum power spectral density as maximum power over any 100 kHz band, thenresolutionBwHzshould be set to 100 kHz, even if the device only uses 20 kHz 🤓.masterDeviceDesc: When a Master Device sends the notification on behalf of a Slave Device, it MAY provide its own descriptor 🎀.masterDeviceLocation: When a Master Device sends the notification on behalf of a Slave Device, it MUST include its own GeoLocation (Section 5.1) 📌.other: Depending on the ruleset, other parameters may be required 🧩. To keep its logic simple, the device MAY include the union of all parameters required by all supported rulesets 🧠. The Database MUST ignore all parameters it doesn't understand 🙈.
4.5.6. SPECTRUM_USE_RESP ✨
okay so the spectrum-use response is literally just the Database saying "got it, thanks bestie" 💖 It acknowledges that it received the notification, and that's the whole vibe 🫶
+---------------------------------------+
|SPECTRUM_USE_RESP |
+----------------------------+----------+
|databaseChange:DbUpdateSpec | OPTIONAL |
|.......................................|
|*other:any | OPTIONAL |
+----------------------------+----------+Parameters:
databaseChange: the Database MAY include a DbUpdateSpec (Section 5.7) to notify the device of a change to the database URI, providing one or more alternate database URIs 🦋 The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec. Main character energy for the device, honestly 💅
other: Database implementations MAY return additional parameters in the response. Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters 🌸
4.6. Device Validation 🔥
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. It's giving efficiency, no cap ✨
When validating one or more Slave Devices, the Master Device sends the Database a request that includes the device identifier, plus 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 5, 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 are outside the scope of this document 🙈
DEV_VALID_REQ(Section 4.6.1) is the device-validation request message.DEV_VALID_RESP(Section 4.6.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 54.6.1. DEV_VALID_REQ
This request is used by a Master Device to determine which Slave Devices are permitted to operate 🎀
+---------------------------------------------+
|DEV_VALID_REQ |
+----------------------------------+----------+
|deviceDescs:list | REQUIRED |---+
|masterDeviceDesc:DeviceDescriptor | OPTIONAL | |
+----------------------------------+----------+ |
V 1..*
+----------------------+
|DeviceDescriptor |
+----------------------+Parameters:
deviceDescs: A DeviceDescriptor (Section 5.2) list is REQUIRED; it specifies the list of Slave Devices that are to be validated 📝
masterDeviceDesc: The Master Device MAY provide its own descriptor ✨
4.6.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. Count them, bestie 🧮
databaseChange: The Database MAY include a DbUpdateSpec (Section 5.7) to notify the device of a change to the database URI, providing one or more alternate database URIs. The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec 🦋
5. Protocol Parameters 👑
This section presents more details of the parameters that make up the PAWS request and response messages 💅 It also includes a subsection that defines response codes.
5.1. GeoLocation 🌈
GeoLocation is used to specify one of the following:
- a single point with optional uncertainty
- 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:
- A "point" with uncertainty is represented using the Ellipse shape.
- A region is represented using the Polygon shape.
The coordinates are expressed using the WGS84 datum [WGS-84], and units are degrees or meters. GeoLocation MAY also include a confidence level, expressed as a percentage. The confidence and uncertainty parameters may be required by some rulesets (see also [RFC7459]) 🥺
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.
+-------------------------------+
|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 specifies the GeoLocation as 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 specifies the GeoLocation as 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: This OPTIONAL parameter expresses the location uncertainty, in meters. It is parameterized using distances along the major and minor axes of the ellipse. The default value for each parameter 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 present, the default value is 0 🧭
exterior: When GeoLocation describes a region, the "exterior" parameter refers to a list of latitude and 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 SHALL NOT cross another connecting line of the same polygon.
- The vertices MUST be defined in a counter-clockwise direction, looking at them from above.
- 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.
- Polygon shapes SHOULD be restricted to a maximum of 15 vertices (16 points that includes the repeated vertex).
Additionally, all vertices are assumed to be at the same altitude 🌙
confidence: The location confidence level, as a percentage, MAY be provided. When this parameter is not provided, the default value is 95. Valid values range from 0 to 100, but, in practice, 100% confidence is not achievable 💯 The confidence value is meaningful only when GeoLocation refers to a point with uncertainty. Realistic, honestly 🥹
5.2. DeviceDescriptor 💖
okay so the device descriptor is basically the device's ID card 🪪 It holds the details that tell the Database exactly who's asking: the manufacturer serial number, the manufacturer's ID, and any other device characteristics the ruleset cares about ✨
+--------------------------------+
|DeviceDescriptor |
+---------------------+----------+
|serialNumber:string | OPTIONAL |
|manufacturerId:string| OPTIONAL |
|modelId:string | OPTIONAL | 1..*
|rulesetIds:list | OPTIONAL |------>string
|.....................|..........|
|*other:any | OPTIONAL |
+---------------------+----------+Parameters:
serialNumber: the manufacturer's serial number is OPTIONAL, though rulesets usually ask for it 🔢 It can be at most 64 octets long.
manufacturerId: this is OPTIONAL, but some rulesets may need it 🏭 It's the name of the manufacturer, so it should be consistent across every device that company makes and different from every other manufacturer's name. Max length is 64 octets.
modelId: OPTIONAL, but some rulesets may require it 📱 Max length is 64 octets.
rulesetIds: this is the list of ruleset identifiers that the device supports (check the Ruleset ID Registry, Section 9.1) 📋 A Database MAY require the device to send this list before it services any requests. If the Database supports none of the rulesets in the list, it MAY refuse to service the requests. For more on ruleset identifiers, see RulesetInfo (Section 5.6). If this list is present, it MUST contain at least one entry 🫶
other: depending on the ruleset, other parameters may be needed 🧚 The Database MUST ignore any parameter in the message it doesn't understand. For more valid parameters, and for how to extend the message with more, check the PAWS Parameters Registry (Section 9.2). For the valid set of parameters for each ruleset, check the PAWS Ruleset ID Registry (Section 9.1) 💜
5.3. AntennaCharacteristics 🦋
antenna characteristics give extra info about the antenna, like its height, its type, and so on 📡 Whether they have to be included in a request depends on the device type and the ruleset. A parameter that's marked as optional may still be required by some rulesets, so keep that in mind 👀
+------------------------------------+
|AntennaCharacteristics |
+-------------------------+----------+
|height:float | OPTIONAL |
|heightType:enum | OPTIONAL |
|heightUncertainty:float | OPTIONAL |
|.........................|..........|
|*characteristics: | OPTIONAL |
| various | |
+-------------------------+----------+Parameters:
height: the antenna height in meters 📏 Heads up, the height can be negative 🙃
heightType: these are the valid values:
AGL: Above Ground Level (default)AMSL: Above Mean Sea Level
heightUncertainty: the height uncertainty in meters 🎯
NOTE: depending on the ruleset, extra antenna characteristics may be required too, like: - antenna direction - antenna radiation pattern - antenna gain - antenna polarization The base protocol doesn't define these, but they can be added to the PAWS Parameters Registry as needed 🧩
5.4. DeviceCapabilities 🌸
device capabilities are extra info the device can share so the Database can work out what spectrum is actually available ✨ If the Database doesn't support device capabilities, it MUST ignore this parameter altogether 🙈
+-------------------------------+
|DeviceCapabilities |
+---------------------+---------+
|frequencyRanges:list |OPTIONAL |--+
|.....................|.........| |
|*other:any |OPTIONAL | |
+---------------------+---------+ | 0..*
V
+--------------------------------+
|FrequencyRange |
+----------------------+---------+
|startHz:float |REQUIRED |
|stopHz:float |REQUIRED |
+----------------------+---------+Parameters:
frequencyRanges: this is an optional list of FrequencyRange entries (Section 5.13) 📻 Each one holds a start and a stop frequency where the device is able to operate. If it's specified, the Database SHOULD NOT return available spectrum that falls outside these ranges 🚫
other: check the PAWS Parameters Registry (Section 9.2) for other possible parameters 🔍 The Database MUST ignore any parameters it doesn't understand.
5.5. DeviceOwner 👑
DeviceOwner holds the ownership info that comes along with device registration 🏠 Some rulesets may ask for extra parameters too.
+-----------------------------+
|DeviceOwner |
+------------------+----------+
|owner:vcard | REQUIRED |
|operator:vcard | OPTIONAL |
+------------------+----------+Parameters:
owner: the vCard contact info for the person or business that owns the device is REQUIRED 📇
operator: the vCard contact info for the device operator is OPTIONAL, but specific rulesets may require it 🧑🔧
Check the PAWS Ruleset ID Registry (Section 9.1) for ruleset-specific rules about mandatory vCard properties 📋 Depending on the ruleset, the Database might have to validate the device-owner info. When that happens, the Database MUST respond with an INVALID_VALUE error (see "Error Codes" (Section 5.17)) if validation fails 😬
All contact info MUST be written using the structure from the "vCard Format Specification" [RFC6350], encoded in JSON [RFC7095]. The vCard spec sets maximum lengths for each parameter, so watch those limits 📏
5.6. RulesetInfo 💅
RulesetInfo carries the parameters for a regulatory domain's ruleset 🌍 You'll see it in the Initialization (Section 4.3), Device Registration (Section 4.4), and Available Spectrum Query (Section 4.5) parts of the protocol.
+------------------------------------------+
|RulesetInfo |
+------------------------------------------+
|authority:string | REQUIRED |
|rulesetId:string | REQUIRED |
|maxLocationChange:float | see description |
|maxPollingSecs:int | see description |
|..........................................|
|*other:any | OPTIONAL |
+------------------------+-----------------+Parameters:
authority: a string saying which regulatory domain the ruleset applies to is REQUIRED 🗺️ It's usually a 2-letter country code from Country Codes - ISO 3166 [ISO3166-1].
rulesetId: the ID of a ruleset for the given authority (see Ruleset ID Registry, Section 9.1) 🆔 The device uses this to figure out what extra behaviour the ruleset needs. To define new ruleset IDs, see "Defining Ruleset Identifiers" (Section 8.1) 🧠
maxLocationChange: the maximum location change in meters is REQUIRED in the Initialization Response (Section 4.3.2), but OPTIONAL everywhere else 📍 Some regulatory domains insist that when a device moves more than this distance, it has to contact the Database to get available spectrum for its new spot. If the Database gives this value in an Available Spectrum Response (Section 4.5.2), it wins over the value from the Initialization Response (Section 4.3.2) 🏆
maxPollingSecs: the maximum number of seconds between requests for available spectrum is REQUIRED in the Initialization Response (Section 4.3.2), but OPTIONAL otherwise ⏱️ The device MUST contact the Database to get available spectrum no less often than this duration. If this value shows up in an Available Spectrum Response (Section 4.5.2), it takes precedence over the Initialization Response (Section 4.3.2) value 💖
other: depending on the ruleset, other parameters may be needed ✨ The device MUST ignore any parameter in the message it doesn't understand. Check the PAWS Parameters Registry (Section 9.2) for other possible parameters 🔎
5.7. DbUpdateSpec 🦋
the Database uses this element to tell devices that its URI is about to change 📣
+-------------------------------+
|DbUpdateSpec |
+---------------------+---------+ +--------------------------+
|databases:list |REQUIRED |------>|DatabaseSpec |
+---------------------+---------+ 1..* +---------------+----------+
|name:string | REQUIRED |
|uri:string | REQUIRED |
+---------------+----------+Parameters:
databases: a list of one or more DatabaseSpec (Section 5.8) entries 📋 A device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec 🔄
5.8. DatabaseSpec 🍓
this element holds the name and URI of a Database 🧚
+--------------------------+
|DatabaseSpec |
+---------------+----------+
|name:string | REQUIRED |
|uri:string | REQUIRED |
+---------------+----------+Parameters:
name: the display name 🏷️ Its maximum length is 64 octets.
uri: the matching URI of the Database 🌐 Its maximum length is 1024 octets.
5.9. SpectrumSpec ✨
okay bestie, the SpectrumSpec element is the big one 💅 It wraps up the whole schedule of available spectrum for a ruleset, so it's basically the main event 🎀
+---------------------------------------+
|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 |
+--------------------+----------+Here's the parameter rundown 🦋
rulesetInfo: this one is REQUIRED 💖 It's a RulesetInfo (Section 5.6) that tells you which regulatory domain and ruleset the spectrum schedule belongs to (check the Ruleset ID Registry in Section 9.1). The device needs that ruleset to make sense of the response 🧠 And anything inside rulesetInfo, likemaxLocationChange, takes priority over what the Initialization Procedure (Section 4.3) gave you. Main character energy for sure 👑spectrumSchedules: the SpectrumSchedule (Section 5.10) list is REQUIRED 🫶 At least one schedule MUST be included, and more than one MAY be included to show future changes to the available spectrum. How far ahead a schedule can show up depends on the ruleset 🌸 If you do pack in more than one, theeventTimeintervals MUST be disjoint and MUST be sorted in increasing time ⏰ A gap in the schedule just means no spectrum is available during that stretch 🙈timeRange: the time range the spec is comprehensive for is OPTIONAL ✨ When it's there, any gaps in the time intervals inside spectrumSchedules that overlap with that range get read by the device as "no spectrum available" 💜frequencyRanges: saying which frequency ranges the spec is comprehensive for is OPTIONAL 🌈 It's a list of disjoint FrequencyRange (Section 5.13) entries. It usually lines up with the frequency ranges the ruleset governs. For TV white space, that could be the VHF and UHF bands of the regulatory domain 📺 A device can mix this with the available-spectrum info in spectrumSchedules to tell apart "unavailable spectrum" from "spectrum nobody gave info about" 🕵️♀️needsSpectrumReport: the Database MAY return true for this one if the spectrumSchedules list isn't empty 🍓 If it doesn't, the Database MAY leave it out completely, and then the default is false. If it's there and true, the device sends a SPECTRUM_USE_NOTIFY (Section 4.5.5) message to the Database. Otherwise the device SHOULD NOT send SPECTRUM_USE_NOTIFY 🚫 Some rulesets mandate this be set to true, so no skipping those 😭maxTotalBwHz: the Database MAY return a limit on the maximum total bandwidth (in hertz) allowed, and that total may or may not be contiguous 🎶 Some rulesets make the Database send this one. When it's in the response, the device needs to apply it to its spectrum-selection logic so the total never goes over the value 💅maxContiguousBwHz: the Database MAY return a limit on the maximum contiguous bandwidth (in hertz) allowed 🦄 Some rulesets require it. When it's present, the device has to apply it in its spectrum-selection logic so no single block of spectrum goes over that value 🧚
5.10. SpectrumSchedule ✨
the SpectrumSchedule element pairs an EventTime (Section 5.14) with a Spectrum (Section 5.11) to say when a chunk of spectrum is valid 🕰️💖
+-------------------------------+
|SpectrumSchedule |
+--------------------+----------+
|eventTime:EventTime | REQUIRED | +--------------------+
|spectra:list | REQUIRED |------->|Spectrum |
+--------------------+----------+ 0..* +--------------------+
|resolutionBwHz:float|
|profiles:list |
+--------------------+Parameters, but make it cute 🎀
eventTime: the EventTime (Section 5.14) is REQUIRED because it's how you say "when" this specification is valid 📅spectra: the Spectrum (Section 5.11) list is REQUIRED 🌷 It lists the available spectrum and the permissible power levels, with one entry per resolutionBwHz. The list MAY be empty when there's no available spectrum at all 🫧
5.11. Spectrum ✨
okay this section is where the power levels actually live 🔥 Available spectrum can be described by an ordered list of spectrum profiles, and those profiles say what power levels are allowed over a set of frequency ranges 🌈 Each Spectrum element gives permissible power levels as maximum power spectral densities over a set resolution bandwidth, resolutionBwHz 📶 Heads up: spectrum profiles are the "availability mask" from the governing ruleset. They are NOT meant to encode device-level transmission-mask requirements 🙅♀️
NOTE: when you're inside the AVAIL_SPECTRUM_RESP (Section 4.5.2), AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4), and SPECTRUM_USE_NOTIFY (Section 4.5.5) messages, the power levels in Spectrum refer to EIRP 💫 Future PAWS extensions might use Spectrum in other contexts with other definitions of power levels, so stay tuned 👀
Some ground rules, bestie 📜
- To handle a ruleset with different "wide-band" and "narrow-band" power levels, PAWS lets you include multiple Spectrum elements in the available-spectrum response, each with a different resolution bandwidth 🎧
- When there are multiple Spectrum elements in the response, each one is a constraint the device has to satisfy (logical AND) 🤝
- Each Spectrum element covers the whole range of frequencies the ruleset governs, rather than splitting those frequencies across several Spectrum elements for the same resolution bandwidth 🧁
- Each spectrum profile is the maximum permissible power spectral density over a contiguous range of frequencies 🍭
- When multiple spectrum profiles show up, they MUST be disjoint and MUST be ordered in non-decreasing frequency value 📊 No overlapping, no backwards ordering, period 🙅♀️
- Gaps in frequencies between consecutive spectrum profiles mean those frequencies are unavailable 🚧
Here's the figure, it's giving diagram energy 🦋
+-------------------------------+
|Spectrum |
+---------------------+---------+
|resolutionBwHz:float |REQUIRED |
|profiles:list |REQUIRED |---+
+---------------------+---------+ | 0..*
V
+-----------------------------+
|SpectrumProfile |
+-------------------+---------+
|list |REQUIRED |
+-------------------+---------+
|
V 2..*
+--------------------------+
|SpectrumProfilePoint |
+----------------+---------+
|hz:float |REQUIRED |
|dbm:float |REQUIRED |
+----------------+---------+Parameters 🍓
resolutionBwHz: this is the resolution bandwidth (in hertz) that the permissible power spectral density is defined over 🎯 For example, FCC regulation would need one spectrum spec at 6 MHz, while ETSI regulation would need two, at 0.1 MHz and 8 MHz 🌍profiles: a SpectrumProfile (Section 5.12) list says what power levels are allowed over a set of frequency ranges 🌷 The list MAY be empty if there's no available spectrum 🫧
Now the examples, which are for illustrative purposes only, babe 🧚 First, permitted power spectral densities for one 6 MHz resolution bandwidth:
[
{
"resolutionBwHz": 6e6,
"profiles": [
[
{"hz": 5.18e8, "dbm": 30.0},
{"hz": 5.30e8, "dbm": 30.0}
],
...
]
}
]This gets read as:
- Over any 6 MHz within the frequency range [518 MHz, 530 MHz), the maximum permitted power is 30.0 dBm (1000 mW) 💖
Next, a fancier one with two different sets of permitted power spectral densities for the same frequencies, but over different resolution bandwidths 🌈
[
{
"resolutionBwHz": 6e6,
"profiles": [
[
{"hz": 5.18e8, "dbm": 30.0},
{"hz": 5.30e8, "dbm": 30.0}
],
...
]
},
{
"resolutionBwHz": 1e5,
"profiles": [
[
{"hz": 5.18e8, "dbm": 27.0},
{"hz": 5.30e8, "dbm": 27.0}
],
...
]
}
]This is interpreted as:
- Over any 6 MHz within the frequency range [518 MHz, 530 MHz), the maximum permitted power is 30.0 dBm (1000 mW), and
- Over any 100 kHz within the frequency range [518 MHz, 530 MHz), the maximum permitted power is 27.0 dBm (500 mW) 🫧
So, for example, you could run two 100 kHz sub-channels inside that 12 MHz range at 500 mW each, which adds up to 1000 mW. Many combinations are possible, as long as they satisfy both conditions 🎀
Last example, with two spectrum profiles that each have a gap from 530 MHz to 536 MHz (for illustrative purposes only) 🦋
[
{
"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 ✨
okay so a spectrum profile is basically an ordered list of (frequency, power) points 💖. Together they draw the max permissible power levels across a range of frequencies as a piecewise linear curve 📈. It's giving graph energy, and the rules are very specific:
- It MUST contain a minimum of two entries.
- The entries in the list MUST be ordered in non-decreasing frequency values.
- Two consecutive points MAY have the same frequency value to represent a "step function".
- Three or more points MUST NOT share the same frequency value.
- The first frequency is inclusive; the last frequency is exclusive.
NOTE: this encoding lets you make "ramps" 🌈, where a line segment's slope can be finite and non-zero. So it's not just flat steps, bestie.
Here's the picture of the SpectrumProfile element 🎀:
+-------------------------------+
|SpectrumProfile |
+---------------------+---------+
|list |REQUIRED |---+
+---------------------+---------+ | 2..*
V
+--------------------------+
|SpectrumProfilePoint |
+----------------+---------+
|hz:float |REQUIRED |
|dbm:float |REQUIRED |
+----------------+---------+Here's what each point in the profile holds:
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 🦋
FrequencyRange is exactly what it sounds like: a frequency range with a start and a stop 💅.
+--------------------------------+
|FrequencyRange |
+----------------------+---------+
|startHz:float |REQUIRED |
|stopHz:float |REQUIRED |
+----------------------+---------+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 tells you the start and stop times of an "event" ✨. It's used to show the time period during which a Spectrum (Section 5.11) is valid.
+---------------------------+
|EventTime |
+-----------------+---------+
|startTime:string |REQUIRED |
|stopTime:string |REQUIRED |
+-----------------+---------+startTime: The inclusive start of the event is REQUIRED.stopTime: The exclusive end of the event is REQUIRED.
Both times use 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 doesn't 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 🫶. You'll find that in "Available Spectrum Response" (Section 4.5.2) and "Available Spectrum Batch Response" (Section 4.5.4). For example:
(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.- 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 wraps up the available spectrum for one location. It shows up inside an AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) batch response, which can hold multiple GeoSpectrumSpec entries. Each entry matches a location from the batch request 🧚.
+----------------------------------+
|GeoSpectrumSpec |
+-----------------------+----------+
|location:GeoLocation | REQUIRED |
|spectrumSpecs:list | REQUIRED |-------+
+-----------------------+----------+ |
| 1..*
V
+--------------+
| SpectrumSpec |
+--------------+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 says whether a device is valid. See Section 4.6.2 for the full picture 🎀.
+---------------------------------------+
|DeviceValidity |
+----------------------------+----------+
|deviceDesc:DeviceDescriptor | REQUIRED |
|isValid:boolean | REQUIRED |
|reason:string | OPTIONAL |
+----------------------------+----------+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 🌈. Its maximum length is 128 octets.
5.17. Error Element 💀
If the Database responds to a PAWS request message with an error, it MUST include an Error element. No skipping this one, periodt 🚨.
+----------------------------------+
|Error |
+----------------+-----------------+
|code:int | REQUIRED |
|message:string | OPTIONAL |
|data:any | see description |
+----------------+-----------------+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. Its maximum length is 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 table below lists predefined and reserved error codes. They're loosely grouped like this:
-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.
Any value that isn't explicitly defined in the Error Codes Table (Table 1) below is unassigned. If you want to define new error codes, check out the PAWS Error Code Registry (Section 9.3) 🍓.
Code Name Description and Additional Parameters
------ ---------------- ---------------------------------------------
0 (reserved)
-100 (reserved)
-101 VERSION The Database does not support the specified
version of the message. This error does not
use any additional data.
-102 UNSUPPORTED The Database does not support the device.
For example, it supports none of the rulesets
specified in the request or does not support
the device, based on its device type, model,
etc. This error does not use any additional
data.
-103 UNIMPLEMENTED The Database does not implement the optional
request or optional feature. This error does
not use any additional data.
-104 OUTSIDE_COVERAGE The specified geolocation is outside the
coverage area of the Database. The Database
MAY include a DbUpdateSpec (Section 5.7) 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.
-105 DATABASE_CHANGE The Database has changed its URI. The
Database MAY include a DbUpdateSpec (Section
5.7) in the error response to provide devices
with one or more alternate database URIs.
The device needs to update its preconfigured
entry for the responding Database with the
alternate Databases listed in the
DbUpdateSpec. 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. This error does not use any
additional data.
-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.
This error does not use any additional data.
-302 NOT_REGISTERED Device registration required, but the device
is not registered. This error does not use
any additional data.
-32000 (reserved) Reserved for JSON-RPC error codes.
to
-32768
Table 1: Error Codes5.17.1. OUTSIDE_COVERAGE Error 🌍
So when the error code is OUTSIDE_COVERAGE, the Database MAY tuck an ErrorData element into the "data" parameter of its Error response 🫶. If it does, that ErrorData carries a DbUpdateSpec (Section 5.7). That's a list of alternate Databases that might be a good fit for the requested location 💖.
+---------------------------+
|Error |
+----------------+----------+
|code:int | REQUIRED |
|message:string | OPTIONAL | +-----------------------------+
|data:ErrorData | OPTIONAL |--->|ErrorData |
+----------------+----------+ +------------------+----------+
|spec:DbUpdateSpec | OPTIONAL |
+------------------+----------+5.17.2. DATABASE_CHANGE Error ✨
okay so when the error code is DATABASE_CHANGE, the Database MAY include an ErrorData element in its Error response as the data parameter 🫶. If it does, that ErrorData has a DbUpdateSpec (Section 5.7) element giving a list of alternate Databases, so the device knows where to go next 🦋.
+---------------------------+
|Error |
+----------------+----------+
|code:int | REQUIRED |
|message:string | OPTIONAL | +-----------------------------+
|data:ErrorData | OPTIONAL |--->|ErrorData |
+----------------+----------+ +------------------+----------+
|spec:DbUpdateSpec | REQUIRED |
+------------------+----------+5.17.3. MISSING Error 🙈
okay this one is kind of a big deal 😭. When the error code is MISSING, the Database MUST include an ErrorData element in its Error response as the data parameter. That ErrorData element MUST include a list of the missing required parameters, and it MAY also include the list of all required parameters 💅.
+---------------------------+
|Error |
+----------------+----------+
|code:int | REQUIRED |
|message:string | OPTIONAL | +---------------------------+
|data:ErrorData | REQUIRED |--->|ErrorData |
+----------------+----------+ +----------------+----------+ 1..*
|parameters:list | REQUIRED |--+
+----------------+----------+ |
|
v
stringParameters:
parameters: a list of one or more parameter names (strings) 🌸. When it makes sense, the name uses dotted notation, like"deviceDesc.serialNumber"🧚.
6. Message Encoding 💖
okay so PAWS is encoded using JSON-RPC [JSON-RPC] (see also "The JavaScript Object Notation (JSON) Data Interchange Format" [RFC7159]) 🎀. Every component in Protocol Functionalities (Section 4) maps to one or more JSON-RPC methods. This section explains how to encode the data models from Sections 4 and 5 into JSON, and it gives some example encodings 🌈. The JSON examples may use ellipses (...) to stand in for extra properties or elements that were left out so the examples stay short ✨.
6.1. JSON-RPC Binding 🦋
The JSON-RPC [JSON-RPC] protocol is built from two basic objects, Request and Response 💜:
- The JSON-RPC Request object wraps up a PAWS functionality (operation) and the request message.
- The JSON-RPC Response object wraps up a PAWS response message and an Error element.
The Database and device MUST support JSON-RPC 2.0 encoding, with one restriction: the "id" parameter in the messages MUST be a string 🙌. The device should generate the "id" uniquely enough to allow the use of JSON-RPC batch 🍓.
The JSON-RPC Request for PAWS looks like this:
{
"jsonrpc": "2.0",
"method": "spectrum.paws.methodName",
"params": <PAWS_REQ>,
"id": "idString"
}Here "method" is the name of a PAWS functionality (operation), and <PAWS_REQ> stands for one of the PAWS request messages linked to that method (see Sections 4.3 through 4.6) 💖. Method names all start with the prefix "spectrum.paws." 🎀.
The non-error JSON-RPC Response for PAWS looks like this:
{
"jsonrpc": "2.0",
"result": <PAWS_RESP>,
"id": "idString"
}Here <PAWS_RESP> stands for one of the PAWS response messages linked to the method, and "id" gets copied over from the request 🫶.
The error JSON-RPC Response for PAWS looks like this:
{
"jsonrpc": "2.0",
"error": {
"code": -102,
"message": "An appropriate error message.",
"data": { ... }
},
"id": "idString"
}The "error" object matches the Error Element (Section 5.17), and "code" is an error code described in that same section 🔥. The Database SHOULD try to use the most specific PAWS error code that applies 💅. If an accurate one isn't available, it SHOULD fall back to the standard JSON-RPC error codes from the JSON-RPC specification 🌸. For example, if the Database gets invalid JSON from the device, it should respond with "-32700", which means a parse error 🙈. As a last resort, the Database MAY send a suitable HTTP 5xx response 😭.
6.1.1. Method Names 🧚
Table 2 lists the method name, request object, and response object for each functionality in Protocol Functionalities (Section 4) 💜.
+-------------------------------------------------------------------+
| Method Name |
| Request |
| Response |
+-------------------------------------------------------------------+
| spectrum.paws.init |
| INIT_REQ (Section 4.3.1) |
| INIT_RESP (Section 4.3.2) |
| |
| spectrum.paws.register |
| REGISTRATION_REQ (Section 4.4.1) |
| REGISTRATION_RESP (Section 4.4.2) |
| |
| spectrum.paws.getSpectrum |
| AVAIL_SPECTRUM_REQ (Section 4.5.1) |
| AVAIL_SPECTRUM_RESP (Section 4.5.2) |
| |
| spectrum.paws.getSpectrumBatch |
| AVAIL_SPECTRUM_BATCH_REQ (Section 4.5.3) |
| AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) |
| |
| spectrum.paws.notifySpectrumUse |
| SPECTRUM_USE_NOTIFY (Section 4.5.5) |
| SPECTRUM_USE_RESP (Section 4.5.6) |
| |
| spectrum.paws.verifyDevice |
| DEV_VALID_REQ (Section 4.6.1) |
| DEV_VALID_RESP (Section 4.6.2) |
+-------------------------------------------------------------------+
Table 2: Method Names6.1.2. JSON Encoding of Data Models 🌈
Encoding the data models from Sections 4 and 5 into JSON [RFC7159] is pretty straightforward, honestly 💅:
- Each data model describes the contents of a JSON object.
- Each parameter in a data model becomes a member of that JSON object:
- The parameter name in the data model is the same as the member name in the JSON object.
- The parameter data type describes the type of the member value.
- Primitive types map to JSON types, as described in Section 4 and repeated here:
string: A JSON string, restricted to UTF-8 encoding
int: A JSON number, without a fractional or exponent part
float: A JSON number
boolean: One of the JSON values, true or false
- The list type maps to a JSON array, except that every value in the array has to be the same type 🍓.
- When a parameter data type refers to another data model, that data model describes a nested JSON object 🧚.
- The encoded JSON object for each Request and Response message in the Method Names Table (Table 2) also includes these members:
type: The name of the message, e.g., "INIT_REQ"
version: The PAWS version, e.g., "1.0"
See the following sections for examples 💖.
6.2. Example Encoding: spectrum.paws.init Method 🎀
Here's an example of the "spectrum.paws.init" JSON-RPC request 🦋:
{
"jsonrpc": "2.0",
"method": "spectrum.paws.init",
"params": {
"type": "INIT_REQ",
"version": "1.0",
"deviceDesc": {
"serialNumber": "XXX",
"fccId": "YYY",
"rulesetIds": ["FccTvBandWhiteSpace-2010"]
},
"location": {
"point": {
"center": {"latitude": 37.0, "longitude": -101.3}
}
}
},
"id": "xxxxxx"
}And here's the matching JSON-RPC response 🫶:
{
"jsonrpc": "2.0",
"result": {
"type": "INIT_RESP",
"version": "1.0",
"rulesetInfos": [
{
"authority": "us",
"rulesetId": "FccTvBandWhiteSpace-2010",
"maxLocationChange": 100,
"maxPollingSecs": 86400
}
]
},
"id": "xxxxxx"
}6.3. Example Encoding: spectrum.paws.getSpectrum Method ✨
okay so here's a full spectrum.paws.getSpectrum JSON-RPC request, bestie 💖 It's giving "ask me for white space and I'll tell you what I know" 🎀
{
"jsonrpc": "2.0",
"method": "spectrum.paws.getSpectrum",
"params": {
"type": "AVAIL_SPECTRUM_REQ",
"version": "1.0",
"deviceDesc": {
"serialNumber": "XXX",
"fccId": "YYY",
"rulesetIds": ["FccTvBandWhiteSpace-2010"]
},
"location": {
"point": {
"center": {"latitude": 37.0, "longitude": -101.3}
}
},
"antenna": {"height": 10.2, "heightType": "AGL"}
},
"id": "xxxxxx"
}Now the response 🦋 This one has a schedule with two time ranges, a spectrum profile for one resolution bandwidth (6 MHz), and power levels for two frequency segments:
- From 518 MHz to 542 MHz
- From 620 MHz to 626 MHz
ngl the real thing is way bigger: each "profiles" list holds (frequency, power) points that cover all the frequencies governed by the ruleset 🌈 For a deeper look at how that gets represented, check out "Spectrum" (Section 5.11) 💅
{
"jsonrpc": "2.0",
"result": {
"type": "AVAIL_SPECTRUM_RESP",
"version": "1.0",
"timestamp": "2013-03-02T14:30:21Z",
"deviceDesc": {
"serialNumber": "XXX",
"fccId": "YYY",
"rulesetIds": ["FccTvBandWhiteSpace-2010"]
},
"spectrumSpecs": [
{
"rulesetInfo": {
"authority": "us",
"rulesetId": "FccTvBandWhiteSpace-2010"
},
"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"
},
"spectra": [
...
]
}
]
}
]
},
"id": "xxxxxx"
}And here's another response, this time with one spectrum profile holding specs for two bandwidth resolutions: 6 MHz and 100 kHz 🍓 Main character energy, honestly 👑
{
"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}
],
[
{"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.4. Example Encoding: DeviceOwner vCard 🧚
okay the DeviceOwner (Section 5.5) data model has member values that are JSON encodings of vCard, as described in "jCard: The JSON format for vCard" [RFC7095] 💜 Here's a little fragment so you can see the vibe:
{
...
"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"]
]
]
}
}7. HTTPS Binding 🔐
this section is all about using "HTTP Over TLS" [RFC2818] (HTTPS) as the transfer mechanism for PAWS 🦋 TLS gives you message integrity and confidentiality between the Master Device and the Database, but only when best current practices are adopted, including recommended cipher suites and modes of operation. So to level up PAWS security and interoperability, implementations of the Database and Master Device MUST follow best current practices defined by "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [RFC7525] 🛡️ This part is seriously important, not gonna lie.
Depending on the prior relationship between a Database and a device, the server MAY require client authentication, as described in the "Transport Layer Security (TLS) Protocol" [RFC5246], to authenticate the device 🫶 When client authentication is required, the Database MUST specify, by prior arrangement, the acceptable root Certification Authorities (CAs) that serve as trust anchors for device certificates.
To help Databases 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 rides in the body of an HTTP POST request, and a PAWS response message rides 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 405 (method not allowed) 🙈
The Database MAY redirect a PAWS request by returning an HTTP 3xx response (as defined by Section 6.4 of "HTTP/1.1: Semantics and Content" [RFC7231]). 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 the Database provided. 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.
okay this part is a little plot twist 😭 Since the device may talk to a Database (which it already authenticated) without any user interaction, when the response code is 301 (Moved Permanently), the device MAY redirect without asking a user for confirmation, even though it came from an HTTP POST method.
The Database SHOULD use HTTP status code "307 Temporary Redirect" to tell the device that it SHOULD resubmit the same request to an alternate URI 🦋 The device MAY revert to the original URI for the very next request, or it MAY keep using the alternate URI for a while, e.g.,:
- For the remainder of its session, or
- For a fixed period of time, or
- Until power cycled, or
- Until it receives another redirect
However, the device does not need to modify its stored list of URIs 💜
For a minimum of two weeks before the URI of the Database changes permanently, the Database MUST use the database-change (DbUpdateSpec (Section 5.7)) mechanism to notify devices, as described in "Configuration Update: Database URI Changes" (Section 4.1.2) 🍓 After the Database has moved, requests to the original URI MAY return HTTP status code 301 (Moved Permanently) to indicate that the device SHOULD resubmit the request, and all future requests, to the indicated alternate URI ✨
8. Extensibility 🌈
this section covers the procedures for extending PAWS 🧚 No extensions should be made that would return sensitive device-specific information in database responses. Seriously, keep the device secrets out of the responses, bestie 🔥
8.1. Defining Ruleset Identifiers 🎀
a ruleset is a set of device-side requirements that the device has been certified for 💖 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 needs additional parameters, they get registered in the PAWS Parameters Registry, as described by Section 9.2. The ABNF syntax [RFC5234] goes like this:
ruleset-id = 1*64ruleset-char
ruleset-char = ALPHA / DIGIT / "_" / "."When you're defining a Ruleset ID, keep these in mind 🦋
- 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.
- The identifier SHOULD include some sort of version information, such as a year and/or version number.
- The maximum length of the identifier is 64 octets.
8.2. Defining New Message Parameters 💅
new request or response parameters for PAWS 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 value syntax MUST be well-defined (e.g., using ABNF or a reference to the syntax of an existing parameter). The grammar looks like this:
param-name = 1*64name-char
name-char = ALPHA / DIGIT / "_"Parameter names use lowerCamelCase by convention. The maximum length of a name is 64 octets 🌸
Unregistered vendor-specific parameter extensions that aren't commonly applicable, and that are specific to the implementation details of the Database where they're used, SHOULD use a vendor-specific prefix that is not likely to conflict with other registered values (e.g., begin with 'companyname') 🫶
8.3. Defining Additional Error Codes 🙈
additional error codes can be registered to extend the set listed in Section 5.17, following the procedures in Section 9.3. If the error code needs additional response parameters, they get 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 doesn't exist, a value from a different range may be used 👑
9. IANA Considerations ✨
okay so PAWS has three registries 📋 💖
- PAWS Ruleset ID Registry (Section 9.1)
- PAWS Parameter Registry (Section 9.2)
- PAWS Error Code Registry (Section 9.3)
All three use the Specification Required policy [RFC5226] 🎀, with a Designated Expert appointed by the IESG 👑. Each registry's description below has the specific criteria the Designated Expert should use when reviewing registrations. The Designated Expert should get advice from the community on the paws@ietf.org mailing list, and the registrant is encouraged to post there before formally requesting the registration from IANA 💌. The goal is that new registrations come with a published specification. But to let values get allocated before the spec is published, the Designated Expert can approve them once it's clear the spec will be published 🦋. Once approved, IANA will post the registrations that aren't meant to be published in an RFC 📮.
9.1. PAWS Ruleset ID Registry 🌈
This specification sets up the "PAWS Ruleset ID Registry" 💅.
Ruleset type names for PAWS messages get registered on the advice of one or more Designated Experts, with Specification Required [RFC5226]. The specification must include a reference to the regulatory domain it applies to. For interoperability, fewer rulesets is actually better than a pile of rulesets with tiny differences 🙈. So the Designated Expert should avoid duplication and encourage the registrant to look for alternatives if there are only small variations from an existing ruleset. The Designated Expert should make sure the proposed registration is complete for its regulatory domain, and may bring in an expert who knows those rules to join the review on the paws@ietf.org mailing list 🧚.
The PAWS Ruleset ID Registry has these columns: 'Ruleset Identifier', 'Reference', and 'Template'. The Template column will link to the registration templates, either posted by IANA or linked to the relevant RFC sections 🔗.
9.1.1. Registration Template 📝
Ruleset identifier: The name of the ruleset. See Section 8.1 of RFC 7545 for the format requirements of this identifier.
Specification document(s): A reference to the document that specifies the parameter, preferably including a URI that can be used to retrieve a copy of the document. Listing the relevant sections is allowed but not required 📖.
Additional Parameter Requirements: A list of additional parameter requirements to go with the ruleset. Quick note: new parameters get registered separately in the PAWS Parameters Registry, as described in Section 8.2 🎀. There are two types of additional parameter requirements:
- Adding new parameters to existing structures, or changing the REQUIRED and OPTIONAL requirements for existing parameters.
- Changing requirements on existing parameter values.
For adding new parameters or changing requirements on existing parameters, the registration should include a table for each affected structure listing that structure's parameter changes. Each table should have a structure name in its heading and these columns:
Parameter name: Name of the parameter added or modified.
Type: Data type of the parameter value.
Requirement: Whether the parameter is REQUIRED or OPTIONAL for the ruleset.
Notes: Any extra notes that might help implementors 💡.
For changing requirements on existing parameter values, the registration should include a table for each affected structure listing that structure's parameter changes. Each table should have a structure name in its heading and these columns:
Parameter name: Name of the parameter.
Type: Data type of the parameter value.
Additional requirements: Additional requirements on the parameter value.
IANA will post each registration template that isn't meant to be published in an RFC 📮.
Note that the Additional Parameter Requirements section can get pretty long 😭, so it won't show up directly in the IANA Ruleset ID Registry table. The table will have a link to the full registration template instead, so it's easy to find the extra requirements 🫶.
9.1.2. Initial Registry Contents 🌸
The PAWS Ruleset ID Registry is built to support any regulatory domain and ruleset 🌍. But the initial contents only have FCC-specific and ETSI-specific entries, because, as of writing, those are the only regulatory domains with finalized rules. This is NOT meant to restrict the protocol to any particular set of authorities 🙅♀️. (Okay, "NOT" is just me being loud. The original says "There is no intent to restrict," so that's the vibe.)
The initial contents of the PAWS Ruleset ID Registry are listed below. Each section corresponds to a single entry in the registry ✨.
9.1.2.1. Federal Communications Commission (FCC) 🇺🇸
For the additional parameters that start with the "fcc" prefix, check out PAWS Parameters Registry Initial Contents (Section 9.2.2) for more info 🔍.
Ruleset identifier: 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] 📜.
Additional Parameter Requirements
Each of the following tables defines additional parameters for the indicated PAWS message. Heads up: the Requirement column lists FCC requirements/optionality rules, NOT PAWS ones 👀.
The FCC requires registration of "Fixed Devices". On top of that, deviceOwner is required in the registration request 🏠:
Registration Request (Section 4.4.1)
+-------------+-------------------+-------------+-------------------+
| Parameter | Type | Requirement | Notes |
| Name | | | |
+-------------+-------------------+-------------+-------------------+
| deviceOwner | DeviceOwner | REQUIRED | For registering |
| | (Section 5.5) | | Fixed Devices |
+-------------+-------------------+-------------+-------------------+ Available Spectrum Request (Section 4.5.1)
+---------------+-----------------------------+-------------+-------+
| Parameter | Type | Requirement | Notes |
| Name | | | |
+---------------+-----------------------------+-------------+-------+
| deviceDesc | DeviceDescriptor (Section | REQUIRED | |
| | 5.2) | | |
+---------------+-----------------------------+-------------+-------+ Available Spectrum Batch Request (Section 4.5.3)
+---------------+-----------------------------+-------------+-------+
| Parameter | Type | Requirement | Notes |
| Name | | | |
+---------------+-----------------------------+-------------+-------+
| deviceDesc | DeviceDescriptor (Section | REQUIRED | |
| | 5.2) | | |
+---------------+-----------------------------+-------------+-------+ DeviceDescriptor (Section 5.2)
+-------------------+--------+-------------+------------------------+
| Parameter Name | Type | Requirement | Notes |
+-------------------+--------+-------------+------------------------+
| serialNumber | string | REQUIRED | Specifies a device's |
| | | | serial number. See |
| | | | Section 5.2. |
| fccId | string | REQUIRED | Specifies a device's |
| | | | FCC certification ID |
| | | | (Section 9.2.2.1). |
| 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 for DeviceOwner (Section 5.5) parameter values 🎀.
DeviceOwner (Section 5.5)
+-----------+-------+-----------------------------------------------+
| Parameter | Type | Additional Requirement |
| Name | | |
+-----------+-------+-----------------------------------------------+
| owner | vCard | The owner is required to contain the |
| | | formatted name of an individual or |
| | | organization using the "fn" property. When |
| | | the name is that of an organization, the |
| | | entry also is required to contain the "kind" |
| | | property, with a value of "org". |
| operator | vCard | The operator entry is required to 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) ✨
Okay bestie, for the extra parameters that start with the etsi prefix, check out PAWS Parameters Registry Initial Contents (Section 9.2.2) for more info 🦋
Ruleset identifier: ETSI-EN-301-598-1.1.1
Specification document(s): This ruleset refers to the ETSI Harmonised Standard [ETSI-EN-301-598] established by ETSI. 📜
Additional Parameter Requirements
Each of the following tables defines additional parameters for the indicated PAWS message. Heads up though: the Requirement column lists ETSI requirements and optionality rules, not PAWS ones 💅
+-------------------------------------------------------------------+
| Parameter Name |
| Type |
| Requirement |
| Notes |
+-------------------------------------------------------------------+
| serialNumber |
| string |
| REQUIRED |
| Specifies a device's serial number (Section 5.2). |
| |
| manufacturerId |
| string |
| REQUIRED |
| Specifies a device's manufacturer's identifier |
| (Section 5.2). |
| |
| modelId |
| string |
| REQUIRED |
| Specifies a device's model identifier (Section 5.2). |
| |
| etsiEnDeviceType |
| string |
| REQUIRED |
| Specifies the device's ETSI device type (Section 9.2.2.3). |
| |
| etsiEnDeviceEmissionsClass |
| string |
| REQUIRED |
| Specifies the device's ETSI device emissions class |
| (Section 9.2.2.4). |
| |
| etsiEnTechnologyId |
| string |
| REQUIRED |
| Specifies the device's ETSI technology ID (Section 9.2.2.5). |
| |
| etsiEnDeviceCategory |
| string |
| REQUIRED |
| Specifies the device's ETSI device category (Section 9.2.2.6). |
+-------------------------------------------------------------------+ AVAIL_SPECTRUM_REQ (Section 4.5.1)
+-------------+--------+-------------+------------------------------+
| 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 is required |
| | | | to respond with generic |
| | | | operating parameters for any |
| | | | Slave Device. |
+-------------+--------+-------------+------------------------------+ Available Spectrum Batch Request (Section 4.5.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 is required |
| | | | to 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.5.2) and AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) messages. Note that this means the Database is modifying the DeviceDescriptor sent by the Master Device to return device-specific restrictions. This is where the Database gets to be a little bossy with the device 👑
+-------------------------------------------------------------------+
| Parameter Name |
| Type |
| Requirement |
| Notes |
+-------------------------------------------------------------------+
| needsSpectrumReport |
| boolean |
| REQUIRED |
| The Database is required to 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 |
| string |
| REQUIRED |
| Specifies a 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. |
+-------------------+-------+-------------+-------------------------+9.2. PAWS Parameters Registry 🌸
This specification establishes the "PAWS Parameters Registry". 🧚
Additional parameters for inclusion in PAWS 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. Similarly, when a parameter is not associated with a ruleset, the Designated Expert should ensure that the parameter name does not have a prefix that is used by existing ruleset parameters (e.g., fcc, etsi) or that is the initials of an organization that has not yet registered anything, but reasonably might. 🙈
The PAWS Parameters Registry includes the following: 'Parameter name', 'Parameter usage location', and 'Specification document(s)'.
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 structures 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 any particular set of authorities. Everyone's invited to the party 🎀
The initial contents of the PAWS Parameters Registry are listed below; each section corresponds to a row of the registry.
9.2.2.1. FCC ID
- Parameter name:
fccId - Parameter usage location:
DeviceDescriptor(Section 5.2) - Specification document(s): This document. Specifies the device's FCC certification identifier. A valid FCC ID is limited to 19 characters in the ASCII value range, as proposed in FCC Administration Topics Review [FCC-Review-2012-10]. For the purposes of the PAWS protocol, the maximum length of the
fccIdvalue is 32 octets. 💖
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", and "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 characterizes 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 maximum length of the string value is 64 octets. Consult the documentation for valid values. 💅
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 PAWS error messages 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. 💜
The PAWS Error Code Registry includes the following: 'Code', 'Name', 'Description and Additional Parameters', and 'Specification Document(s)'. 📋
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 and Additional Parameters: Description of the error and its associated parameters, if any. It also lists 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. 🎀
9.3.2. Initial Registry Contents 🌸
Initial registry contents are defined in the Error Codes Table (Table 1). 🦋
The registry will also include the error-code categories describing -100s, -200s, and -300s as a note (see "Error Codes" (Section 5.17)). ✨
10. Security Considerations 🔐
Okay bestie, this part is SERIOUS. Read it carefully. 💀
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 (PAWS) Databases: Use Cases and Requirements" [RFC6953]. 📡
By using PAWS, the Master Device and the Database expose themselves to the following risks: 😭
- Accuracy: The Master Device receives incorrect spectrum-availability information.
- Privacy:
- An unauthorized entity intercepts identifying data for the Master Device or its Slave Devices, such as serial number and location.
- Where Databases are required to take device registrations and/or maintain request logs, there could be unauthorized access to such information.
Protection from these risks depends on the success of the following steps: 🧩
- The Master Device must determine the address of a proper Database.
- The Master Device must connect to the proper Database.
- The Database must determine or compute accurate spectrum-availability information.
- PAWS messages must be transmitted unmodified between the Database and the Master Device.
- PAWS messages must be encrypted between the Database and the Master Device to prevent exposing private information.
- For a Slave Device, the spectrum-availability information also must be transmitted unmodified and securely between the Master Device and the Slave Device.
- When a Listing Server is required, any attack that would prevent reaching a Listing Server would result in all devices relying on that Listing Server ceasing their use of any white space.
- No future extensions to PAWS can allow the return of sensitive information, such as device information or logs.
- The Database must not allow unauthorized access to device information and request logs and should publish and implement privacy policies regarding their use.
Of these, only steps 1, 2, 4, 5, and 8 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. 🌈
Use of "HTTP Over TLS" [RFC2818], assuming the PKI used is not compromised, ensures steps 2, 4, and 5, as detailed in the following sections: 🔒
- "Assurance of Proper Database" (Section 10.1)
- "Protection against Modification" (Section 10.2)
- "Protection against Eavesdropping" (Section 10.3)
Any specification for an alternate transport MUST define mechanisms that ensure each of these steps. 🚫
In addition to the privacy risks described above, information provided in DeviceDescriptor (Section 5.2) and DeviceOwner (Section 5.5), along with device location, may allow a database administrator to track the activity and location of a device and its user over time. Risks of secondary use of such tracking information, including sharing with third parties, require out-of-band mitigation, such as public statements or contractual terms. Furthermore, while it is understandable that regulators require DeviceOwner information for higher-power fixed white-space devices, for privacy concerns, regulators should not require DeviceOwner information for mobile devices. Similarly, regulators should require, and implementations should provide, device location at a level of granularity only as precise as necessary to support accurate database responses. 🕵️♀️
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, 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), checks of the subjectAltName 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's certificate. A Master Device should allow for the fact that a Database can change its Certification 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 cipher suites. ✨
10.3. Protection against Eavesdropping 👀
Using HTTP over TLS, messages protected by appropriate cipher suites are also protected from eavesdropping or otherwise unrestricted reading by unauthorized parties en route. 💜
10.4. Client Authentication Considerations ✨
okay so the Database can tell a device what spectrum it's allowed to use 📡, but it literally cannot make the Master Device stick to those frequencies (or any of them) 😭. A sketchy device can just operate without ever talking to a Database at all 💀. Also, a bad actor might send fake SPECTRUM_USE_NOTIFY (Section 4.5.5) messages, BUT in regulatory domains with established rules those notifications don't change the available-spectrum answers, so no harm can come from them 💅. So client authentication is not required for the core PAWS (although specific regulatory domains may still require it) 🔐.
Depending on how a Database and Master Device already know each other, the Database MAY require client authentication 🫶. TLS can handle client auth, but there are some considerations:
- The Database gotta name the CAs it accepts, and the Master Device must have a certificate rooted at one of those CAs 👑.
- As indicated in Section 3.2 of "HTTP Over TLS" [RFC2818], the TLS client authentication procedure only proves the device has a certificate chain rooted in an appropriate CA (or a self-signed certificate) 🙈. The Database wouldn't know what the client identity is supposed to be unless it has some external source of info. Distributing and managing that info, including revocation lists, is outside the scope of this document 🧚.
- Authentication schemes are only as secure as the secrets or certificates kept behind them 🔑. When there are a vast number of deployed devices using PAWS, the odds that device keys never leak get pretty small 😬. Implementations should consider how to manage the system in case a leak does happen 🌈.
11. References 📚
11.1. Normative References
- [JSON-RPC] "JSON-RPC 2.0 Specification",
<http://www.jsonrpc.org/specification>. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. - [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/RFC2818, May 2000,
<http://www.rfc-editor.org/info/rfc2818>. - [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<http://www.rfc-editor.org/info/rfc3339>. - [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, "Transport Layer Security (TLS) Session Resumption without Server-Side State", RFC 5077, DOI 10.17487/RFC5077, January 2008,
<http://www.rfc-editor.org/info/rfc5077>. - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>. - [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. - [RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV Presence Information Data Format Location Object (PIDF-LO) Usage Clarification, Considerations, and Recommendations", RFC 5491, DOI 10.17487/RFC5491, March 2009,
<http://www.rfc-editor.org/info/rfc5491>. - [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, DOI 10.17487/RFC6350, August 2011,
<http://www.rfc-editor.org/info/rfc6350>. - [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, DOI 10.17487/RFC7095, January 2014,
<http://www.rfc-editor.org/info/rfc7095>. - [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014,
<http://www.rfc-editor.org/info/rfc7159>. - [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014,
<http://www.rfc-editor.org/info/rfc7231>. - [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015,
<http://www.rfc-editor.org/info/rfc7525>.
11.2. Informative References
- [ETSI-EN-301-598] European Telecommunication Standards Institute (ETSI), "ETSI EN 301 598 (V1.1.1): White Space Devices (WSD); Wireless Access Systems operating in the 470 MHz to 790 MHz TV broadcast band; Harmonized EN covering the essential requirements of article 3.2 of the R&TTE Directive", April 2014,
<http://www.etsi.org/deliver/etsi_en/301500_301599/301598/01.01.01_60/en_301598v010101p.pdf>. - [FCC-CFR47-15H] U. S. Government, "Electronic Code of Federal Regulations, Title 47, Part 15, Subpart H: Television Band Devices", December 2010,
<http://www.ecfr.gov/cgi-bin/text-idx?rgn=div6&view=text&node=47:1.0.1.1.16.8>. - [FCC-Review-2012-10] Federal Communications Commission, "Administration Topics Review", October 2012,
<http://transition.fcc.gov/bureaus/oet/ea/presentations/files/oct12/2b-TCB-Admin-Issues-Oct-2012-GT.pdf>. - [ISO3166-1] "Country Codes",
<http://www.iso.org/iso/country_codes.htm>. - [RFC6953] Mancuso, A., Ed., Probasco, S., and B. Patil, "Protocol to Access White-Space (PAWS) Databases: Use Cases and Requirements", RFC 6953, DOI 10.17487/RFC6953, May 2013,
<http://www.rfc-editor.org/info/rfc6953>. - [RFC7459] Thomson, M. and J. Winterbottom, "Representation of Uncertainty and Confidence in the Presence Information Data Format Location Object (PIDF-LO)", RFC 7459, DOI 10.17487/RFC7459, February 2015,
<http://www.rfc-editor.org/info/rfc7459>. - [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,
<http://earth-info.nga.mil/GandG/publications/tr8350.2/tr8350_2.html>.
Appendix A. Database Listing Server Support 🧭
as discussed in "Database Discovery" (Section 4.1), some regulatory domains preconfigure devices with the URI of a listing server 🗂️. Devices can connect to it to get a list of Databases certified by that regulatory domain. Regulatory domains may require the device to periodically contact the Database Listing Server to validate and/or update its list of certified Databases ⏰. If the device can't validate its list within the required period, regulatory rules may require the device to treat that as equivalent to having no available spectrum 🚫.
A sample JSON response from a Database Listing Server might look like this 👀:
{
"lastUpdateTime": "2014-06-28T10:00:00Z",
"maxRefreshMinutes": 1440
"dbs": [
{
"name": "Some Operator",
"uris": [
{
"uri": "https://example.some.operator.com",
"protocol": "paws"
},
...
]
},
...
]
}The parameters in this sample message are:
lastUpdateTime: The time at which the database entries were last updated.maxRefreshMinutes: The maximum interval, expressed in minutes, that is allowed between device requests to the Database Listing Server.dbs: A list of entries for certified Databases, each containing the following:name: The name of the database operator.uris: One or more URIs for each Database, allowing a Database to support more than one protocol.uri,protocol: Each protocol supported by a certified Database is associated with a separate URI (PAWS protocol URI shown).
Acknowledgments 🫶
the authors gratefully thank everyone who helped out: 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, Kalle Kulsmanen, Warren Kumari, Paul Lambert, Andy Lee, Anthony Mancuso, Basavaraj Patil, Scott Probasco, Brian Rosen, Andy Sago, Peter Stanforth, John Stine, and Juan Carlos Zuniga 💜.
Contributors 🌸
this document draws heavily from draft-das-paws-protocol and draft-wei-paws-framework. The editor would like to specifically call out and thank the contributing authors of those two documents 🙌.
Donald Joslyn
Spectrum Bridge Inc.
1064 Greenwood Blvd.
Lake Mary, FL 32746
United States
EMail: d.joslyn@spectrumbridge.com
Xinpeng Wei
Huawei
Phone: +86 13436822355
EMail: weixinpeng@huawei.comAuthors' Addresses 💖
Vincent Chen (editor)
Google
1600 Amphitheatre Parkway
Mountain View, CA 94043
United States
EMail: vchen@google.com
Subir Das
Applied Communication Sciences
150 Mount Airy Road
Basking Ridge, NJ 07920
United States
EMail: sdas@appcomsci.com
Lei Zhu
Huawei
Phone: +86 13910157020
EMail: lei.zhu@huawei.com
John Malyar
iconectiv (formerly Telcordia Interconnection Solutions)
444 Hoes Lane/RRC 4E1106
Piscataway, NJ 08854
United States
EMail: jmalyar@iconectiv.com
Peter J. McCann
Huawei
400 Crossing Blvd, 2nd Floor
Bridgewater, NJ 08807
United States
Phone: +1 908 541 3563
EMail: peter.mccann@huawei.com📦 where this page comes from
- ietf: rfc7545 2015-05
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms