Application Area Working Group S. Das, ed. Internet-Draft ACS Intended status: Standards Track J. Malyar Expires: January 15, 2013 Telcordia D. Joslyn SBI July 14, 2012 Device to Database Protocol for White Space draft-das-paws-protocol-02 Abstract This document describes the `Protocol to Access White Space database (PAWS)' that uses HTTP/TLS as transport. The protocol is used for retrieving the necessary TV white space information (e.g., channel, frequency, transmitted power) at a given location and time from a database that is operating under a regulatory domain. The document includes the protocol functionalities, its elements, corresponding data model and recommends its encoding scheme. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 15, 2013. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents Das, ed., et al. Expires January 15, 2013 [Page 1] Internet-Draft Device to Database Protocol July 2012 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Convention used in this document . . . . . . . . . . . . . . . 3 2. Terminology and abbreviations used in this document . . . . . 3 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Protocol Description . . . . . . . . . . . . . . . . . . . . . 6 5. Protocol Functionalities and Messages . . . . . . . . . . . . 7 5.1. Master WSD Initialization . . . . . . . . . . . . . . . . 7 5.2. Master WSD Registration . . . . . . . . . . . . . . . . . 8 5.3. Database Query . . . . . . . . . . . . . . . . . . . . . . 9 5.4. WSD Validation . . . . . . . . . . . . . . . . . . . . . . 10 6. Data Objects, Elements and Attributes . . . . . . . . . . . . 11 6.1. Data Element Definition . . . . . . . . . . . . . . . . . 17 6.2. Attribute Definition . . . . . . . . . . . . . . . . . . . 19 7. Example Messages with JSON Encoding . . . . . . . . . . . . . 23 8. The Digest Authentication Scheme . . . . . . . . . . . . . . . 29 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 30 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 11.1. Normative References . . . . . . . . . . . . . . . . . . . 30 11.2. Informative References . . . . . . . . . . . . . . . . . . 31 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 Das, ed., et al. Expires January 15, 2013 [Page 2] Internet-Draft Device to Database Protocol July 2012 1. Convention used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Terminology and abbreviations used in this document Following definitions are copied from [I-D.ietf-paws-problem-stmt-usecases-rqmts] White Space Radio spectrum which is not fully occupied at a specific location and time. TV White Space TV white space refers specifically to radio spectrum which has been allocated for TV broadcast, but is not occupied by a TV broadcast, or other assigned user (such as a wireless microphone), at a specific location and time. White Space Device (WSD) A device which opportunistically uses some part of white space spectrum. A white space device can be an access point, base station, a portable device or similar. A white space device may be required by local regulations to query a database with its location to obtain information about available spectrum. Database In the context of white space and cognitive radio technologies, the database is an entity which contains, but is not limited to, current information about available spectrum at any given location and time as required by the regulatory policies. Master WSD A device which is required to query the WS Database to find out the available operating channels. Slave WSD A device which uses the spectrum made available by a master device and cannot query the database directly. Following definitions are copied from FCC 10-174, September, 2010 Das, ed., et al. Expires January 15, 2013 [Page 3] Internet-Draft Device to Database Protocol July 2012 [FCC] TV Bands Database (TVBD) A database system that maintains records of all authorized services in the TV frequency bands, is capable of determining the available channels as a specific geographic location. Fixed Device A TVBD that transmits and/or receives radio communication signals at a specified fixed location. Mode I personal/portable device A personal/portable TVBD that does not use an internal geolocation capability and access to a TV bands database to obtain a list of available channels. Mode II personal/portable device A personal/portable TVBD that uses an internal geo-location capability and access to a TV bands database, either through a direct connection to the Internet or through an indirect connection to the Internet by way of fixed TVBD or another `Mode II` TVBD, to obtain a list of available channels. 3. Introduction Services offered via TV Whitespaces initiative will require a variety of devices and services each acting in accord with rules provided by the regulatory bodies and industries. Along with other things, the service architecture requires the `Master WSD` to access the `Database`(e.g. TV Whitespace database) to obtain the necessary information that could be utilized at their location to provide the service. In this document, we focus on this aspect of the overall system: the interface between `Master WSD` and `Database`. Figure 1 depicts the device-to-database interface architecture and highlights the scope of this document. The definition of WSD may differ from one regulatory authority to another. For example, by United States (US) FCC rules, TV WSD is referred to `Fixed` and `Personal/Portable device` (e.g., `Mode II` personal/portable device`) [FCC]. The `Fixed and personal/portable TV WSDs devices` may additionally support other TV WSDs (e.g. `Mode I` personal/portable device per US FCC rules [FCC]) to establish wireless broadband services. `Mode I` TV WSDs may also access the Das, ed., et al. Expires January 15, 2013 [Page 4] Internet-Draft Device to Database Protocol July 2012 database to obtain the relevant information at their location. \|/ | | |-|---------| | Fixed/ | .-------. | Mode II | / \ | WSD | / \ |-----------| |(Master) |=========( Internet )=========| Database | |-----------| \ / |(e.g. TVWS)| | \ / |-----------| | \.-----./ | \|/ | < --Device-to-Database Interface-> | | | |Air IF | | |-|---------| | Mode I | | WSD | | (Slave) | |-----------| Figure 1: Device-to-Database Interface Architecture Several use cases and requirements for use of White Space spectrum are described in document [I-D.ietf-paws-problem-stmt-usecases-rqmts]. This document describes an interface protocol between `Master device` and `Database` called PAWS that uses HTTP/TLS as transport and defines the protocol functionalities, messages, its data object models and recommend the encoding scheme. This protocol can be used by the `Master WSD` to obtain TV Whitespace information (e.g., Channel, frequency, transmitted power and so on)in a given location and time from a white space database that is operating under a regulatory domain. This document identifies the need to support the requirements by the regulatory authorities of different countries. While some countries have published their requirements (e.g.,[FCC], [OfCom]), others are expected to provide in near future. This specification attempt to Das, ed., et al. Expires January 15, 2013 [Page 5] Internet-Draft Device to Database Protocol July 2012 define an extensible protocol and its data models that should accommodate the need for various regulatory authorities. 4. Protocol Description Figure 2 shows the interface protocol stack. The interface protocol (PAWS) is an application protocol that uses HTTP/TLS as transport. +-+-+-+-+-+-+-+-+-+-+-+-+ | PAWS | +-+-+-+-+-+-+-+-+-+-+-+-+ | HTTP/TLS | +-+-+-+-+-+-+-+-+-+-+-+-+ | TCP | +-+-+-+-+-+-+-+-+-+-+-+-+ | IP | +-+-+-+-+-+-+-+-+-+-+-+-+ Figure 2: Example Protocol Layer The `Master WSD` uses the HTTPS-enabled PAWS to perform the following operations. The protocol functionalities and message flows are described in Section 5. o The device MUST first locate or discover the URI for the database to send the PAWS messages. The URI for the database SHOULD be obtained from an authorized and authenticated entity. The discovery of database URI details are outside the scope of this document. However, it is RECOMMENDED that the type of URI provided by database discovery method SHOULD be an HTTPS URI. o Once the TLS handshake between device and database server has finished, the `Master WSD` initiates the initial service request to WS database server in the body of an HTTPS request via the POST method as described in [RFC2818] to exchange certain information including the capability exchange. The database responds with the message in the body of the HTTPS response. The database uses a server certificate issued by a well-known certificate authority. The devices can authenticate the server side certificate by configuring the trust to the issuing authority. The device authentication is performed by the database server at the PAWS layer by using `Digest Authentication`. Das, ed., et al. Expires January 15, 2013 [Page 6] Internet-Draft Device to Database Protocol July 2012 o Once authenticated, the device registers with the WS database and establishes certain operational parameters as required by the spectrum management authority. The registration messages are handled via same HTTP method as described above. The WS database returns the result of the registration. o After device and server are mutually authenticated and the device is authorized to obtain the service, the device sends a query message to the WS database with the required parameters for obtaining WS channel information. The channel query messages are handled via same HTTP method as described above. The WS database returns the available channel information. o Depending upon the regulatory and operational requirements, `Master WSD` may need to verify the identity of the `Slave WSDs`. `Master WSD` sends a validation message to the WS database with the required information. The device validation messages are handled via same HTTP method as described above. The WS database returns the result of the validation. o The data model and its relationship with data-objects, data- elements and attributes are described in Section 6. The example messages are encoded in JSON structure and is described in Section 7. Other encodings (such as XML) may be added in the future version of the document. However, all encoding should follow the same data model. 5. Protocol Functionalities and Messages Following are the protocol functionalities and message flows of the WS Application protocol. 5.1. Master WSD Initialization The `Master WSD` initialization is the process of a device establishing initial connection to the database. Each time the `Master WSD` powers up or opens up a communication with the database, it exchanges these messages. The principle purpose of the initialization messages are: i) exchange the capability information related to regulatory domains and operations; ii) the device to request parameters that will initiate the client authentication process. In particular, this will allow the device and server to know in which regulatory domain the service is requested for, the sequence of protocol operations necessary to fulfill the regulatory requirements. In addition, PAWS client in this step will obtain the authentication parameters from the server that will enable client device to proof it authenticity and provide message integrity during Das, ed., et al. Expires January 15, 2013 [Page 7] Internet-Draft Device to Database Protocol July 2012 the entire protocol operation at the PAWS application layer. The confidentiality is achieved at the HTTPS layer. However, the information needed for these initial message exchanges at the PAWS layer may vary depending upon the deployment and regulatory requirements. In this document we describe the use digest of authentication scheme for device authentication similar to the use in [RFC3261], the details of which are described in Section 8. `INIT-REQ` and `INT-RESP` messages are used to perform the Master WSD initialization with the database. Figure 3 depicts the call flow of the initialization message. Master WSD Database | | | INT-REQ | |---------------------->| | INT-RESP | |<----------------------| | | | | Figure 3: WSD Initialization Message Flow 5.2. Master WSD Registration The `Master WSD` registration is the process of a device establishing certain operational parameters with the database, as required by the spectrum management authority. FCC rules, for example, requires that `Fixed Devices` register as owner and/or operator contact information. `Fixed Devices` may also register their fixed location and antenna height parameters with the database. Registration is required upon its initial contact with the database, or when its registered parameters change (e.g., a Fixed device is redeployed at a new location, or its antenna height is adjusted,) or registration life time expires. However, this functionality may be optional in certain regulatory domains. `REG-REQ` and `REG-RESP` messages are used to perform the `Master Device` registration with the database. Figure 4 depicts the call flow of the registration message. Das, ed., et al. Expires January 15, 2013 [Page 8] Internet-Draft Device to Database Protocol July 2012 Master WSD Database | | | REG-REQ | |---------------------->| | REG-RESP | |<----------------------| | | | | Figure 4: WSD Registration Message Flow 5.3. Database Query In order of obtain the available channel and other information `Master WSD` needs to query the `Database`. In certain regulatory environment, it may be required to be authenticated and registered before a `Master WSD` can query the database and in other domains, the requirements may be vary. `Master WSD` will perform `Initialization` and `Registration` procedures as and when required before querying the database. When the `Master WSD` sends a query to the `Database`, it sends its location (e.g., Geo-location) along with other parameters. `Database` returns an array of channels within the scope of the request (e.g., VHF/UHF) and regulatory authority where the returned elements contain the channel frequency range, availability indicator, operating power, event management (indicator when channel is scheduled or is not available), and so on. It may also include other parameters depending upon the regulatory requirements. `AVAIL-CHAN-REQ` and `AVAIL-CHAN-RESP` messages are used by devices for querying the database in a given location. 'USE-CHAN-NOTIFY' message is used by the `Master WSD` to notify the database which channels are anticipated to be used in that location by the master WSD or associated slave devices. 'USE-CHAN-RESP' message is used by the database to positively or negatively acknowledge (ACK/NACK) the channel availability. Figure 5 depicts the call flow of the database query message. Das, ed., et al. Expires January 15, 2013 [Page 9] Internet-Draft Device to Database Protocol July 2012 Master WSD Database | AVAIL-CHAN-REQ | |---------------------->| | AVAIL-CHAN-RESP | |<----------------------| | | | USE-CHAN-NOTIFY | |---------------------->| | | | USE-CHAN-RESP | |<----------------------| | | Figure 5: Query Message Flow 5.4. WSD Validation The WSD validation is the process by which slave WSDs can be validated by the database. For example, by US FCC rule, the `TVWS Fixed or Mode II` device provides service to a Mode I device only after the Mode I is validated by the TVWS database. To facilitate this validation, `Database` needs to support `WSD Validation` capability. However, the requirement may vary from one regulatory domain to another. `DEV-VALID-REQ` and `DEV-VALID-RESP` messages are used by `Master WSD` for `Slave WSD` validation with the database. Figure 6 depicts the call flow of validation message. Master device Database | | | DEV-VALID-REQ | |---------------------->| | DEV-VALID-RESP | |<----------------------| | | Figure 6: WSD Validation Message Flow Das, ed., et al. Expires January 15, 2013 [Page 10] Internet-Draft Device to Database Protocol July 2012 6. Data Objects, Elements and Attributes This section presents the data objects, data elements and attribute list and show their relationships. Protocol messages are mapped to data-objects and then elements are derived based on necessary information that need to be exchanged. Parameters and listed as attributes per data elements. The model is structured in such a way that additional data-objects, elements and attributed can be added easily as new requirements emerge. In addition, there could be a need for vendor-specific attributes as things evolve. Each data object (e.g., REQ, RESP, NOTIFY) will contain a set of data elements which will carry a set of attributes. In general, `REQ` and `NOTIFY` data objects are included in the body of the HTTPS Request message and is initiated by the `Master WSD` while `RESP` data object is included in the body of the HTTPS Response message and is generated by the `WS Database`. The absence or presence of the data elements and attributes within a data object is mostly dictated by the regulatory domain where the device and the database are operating. However, some data elements are independent of the regulatory domain and are essential for the protocol operation. For example, the `Capabilityinfo`, `ProtocolInfo`, `Devicelocation` `AvailChannellist` and `Authinformation` in this version are mandatory while others are optional and their use will depend upon the regulatory domain rules where the service is being offered. +----+ +------------+ +--------+ +---------+ |PAWS|-|Data Object |------| Element|-----------|Attribute| +----+ +-+----------+ +--+-----+ +--+------+ | | | | | | | ++====================+==================+ | || |-----------------+| | || |Devicetype || | || |type=Fixed, || | || | Portable || | || |Deviceidentity || | ||------------------+ |type=string || | ||Capabilityinfo | |Deviceserialno || | ||type=capability |-+type=string || | ||------------------+ |Device RAT || | || |type=string || | || |Authority || | || |type=string || Das, ed., et al. Expires January 15, 2013 [Page 11] Internet-Draft Device to Database Protocol July 2012 | || |-----------------+| | || | | | ||---------------+ |------------+ | | ----------------+ ||ProtocolInfo | |Protoversion| | |-|Initialization | ||type=proto |----+type=float | | | |REQ/RESP |-+|---------------+ |Messagetype | | | +---------------+ || |type=string | | | || |Resultcode | | | || |type=boolean| | | || |Errorcode | | | || |type=number | | | || |------------+ | | || | | | ||-----------------+ |------------+ | | ||Authinformation | |Authscheme | | | ||type=authinfo |--+type=string | | | ||-----------------+ |Realm | | | || |type=string | | | || |Nonce | | | || |type=string | | | || |cnonce | | | || |type=string | | | || |qop | | | || |type=string | | | || |------------+ | | ++====================+==================+ | | | | | | | | | ++====================+==================+ | || |-----------------+| | || |Devicetype || | || |type=Fixed, || | || | Portable || | || |Deviceidentity || | ||------------------+ |type=string || | ||Capabilityinfo | |Deviceserialno || | ||type=capability |-+type=string || | ||------------------+ |DeviceRAT || | || |type=string || | || |Authority || | || |type=string || | || |-----------------+| | || | | | ||---------------+ |------------+ | | ||ProtocolInfo | |Protoversion| | | ||type=proto |----+type=float | | | ||---------------+ |Messagetype | | | || |type=string | | Das, ed., et al. Expires January 15, 2013 [Page 12] Internet-Draft Device to Database Protocol July 2012 | || |Resultcode | | | || |type=boolean| | | || |Errorcode | | | || |type=number | | | || |------------+ | | || | | | || |---------------+ | | || |Latitude | | | || |type=float | | | || |longitude | | | || |type=float | | | || |longitude | | | ||-----------------+ |type=float | | | +---------------+ ||Devicelocation | |Locuncertainty | | |-|Registration | ||type=geoloc,civic|--+type=number | | | |REQ/RESP |-+|-----------------+ |Locconfidence | | | +---------------+ || |type=number | | | || |HAGL | | | || |type=float | | | || |HAGLuncertainty| | | || |type=number | | | || |Antennatype | | | || |type=int | | | || |Geolocationcode| | | || |type=string | | | || |---------------+ | | || | | | || |-----------------+| | || |Ownername || | || |type=string || | || |Address || | ||-----------------+ |type=string || | ||Deviceowner | |phonenumber || | ||type=ownerinfo; |--+type=alphanumeric|| | || operatorinfo| |Email || | ||-----------------+ |type=alphanumeric|| | || |Operatorname || | || |type=string || | || |address || | || |type=string || | || |phonenumber || | || |type=alphanumeric|| | || |Email || | || |type=alphanumeric|| | || |-----------------+| | ||-----------------+ |------------+ | | ||Authinformation|-| |Authscheme | | | ||type=authinfo |--+type=string | | Das, ed., et al. Expires January 15, 2013 [Page 13] Internet-Draft Device to Database Protocol July 2012 | ||-----------------+ |Realm | | | || |type=string | | | || |Nonce | | | || |type=string | | | || |cnonce | | | || |type=string | | | || |qop | | | || |type=string | | | || |------------+ | | ++====================+==================+ | | | | | | | | | ++====================+==================+ | || |-----------------+| | || |Devicetype || | || |type=Fixed, || | || | Portable || | || |Deviceidentity || | ||------------------+ |type=string || | ||Capabilityinfo | |Deviceserialno || | ||type=capability |-+type=string || | ||------------------+ |DeviceRAT || | || |type=string || | || |Authority || | || |type=string || | || |-----------------+| | || | | | ||---------------+ |------------+ | | ||ProtocolInfo | |Protoversion| | | ||type=proto |----+type=float | | | ||---------------+ |Messagetype | | | || |type=string | | | || |Resultcode | | | || |type=boolean| | | || |Errorcode | | | || |type=string | | | || |------------+ | | || |---------------+ | | || |Latitude | | | || |type=float | | | || |longitude | | | || |type=float | | | || |longitude | | | ||-----------------+ |type=float | | | +---------------+ ||Devicelocation | |Locuncertainty | | |-|Databasequery | ||type=geoloc,civic|--+type=number | | | |REQ/RESP; |-+|-----------------+ |Locconfidence | | | |NOTIFY/RESP | || |type=number | | Das, ed., et al. Expires January 15, 2013 [Page 14] Internet-Draft Device to Database Protocol July 2012 | +---------------+ || |HAGL | | | || |type=float | | | || |HAGLuncertainty| | | || |type=number | | | || |Antennatype | | | || |type=int | | | || |Geolocationcode| | | || |type=string | | | || |---------------+ | | || | | | ||-----------------+ |-----------------+| | ||AvailChannellist | |Requesttype || | ||type=channelarray|--+type=allchannels,|| | ||-----------------+ | availableonly || | || |Channelno || | || |type=list || | || |Minfreq || | || |type=string || | || |Maxfreq || | || |type=string || | || |MaxEIRP || | || |type=float || | || |DateTime || | || |type=alphanumeric|| | || |Duration || | || |type=seq(ticks, || | || | unit) || | || |Availability || | || |type=string || | || |-----------------+| | || | | | ||-----------------+ |--------------+ | | ||UsedChannellist | |usedchannelno | | | ||type=channelarray|--+type=list | | | ||-----------------+ |Frequenyrange | | | || |type=string | | | || |MaximumEIRP | | | || |type=float | | | || |--------------+ | | || | | | ||-----------------+ |------------+ | | ||Authinformation|-| |Authscheme | | | ||type=authinfo |--+type=string | | | ||-----------------+ |Realm | | | || |type=string | | | || |Nonce | | | || |type=string | | | || |cnonce | | Das, ed., et al. Expires January 15, 2013 [Page 15] Internet-Draft Device to Database Protocol July 2012 | || |type=string | | | || |qop | | | || |type=string | | | || |------------+ | | ++====================+==================+ | | | | | | | | | ++====================+==================+ | || |-----------------+| | || |Devicetype || | || |type=Fixed, || | || | Portable || | || |Deviceidentity || | ||------------------+ |type=string || | ||Capabilityinfo | |Deviceserialno || | ||type=capability |-+type=string || | ||------------------+ |DeviceRAT || | || |type=string || | || |Authority || | || |type=string || | || |-----------------+| | || | | | ||---------------+ |------------+ | | ||ProtocolInfo | |Protoversion| | | ||type=proto |----|type=float | | | ||---------------+ |Messagetype | | | || |type=string | | | || |Resultcode | | | || |type=boolean| | | || |Errorcode | | | || |type=string | | | || |------------+ | | || | | | || |---------------+ | | || |Latitude | | | || |type=float | | | || |longitude | | | || |type=float | | | || |longitude | | | ||-----------------+ |type=float | | | +----------------+||Devicelocation | |Locuncertainty | | |-|Devicevalidation|||type=geoloc,civic|--+type=number | | | |REQ/RESP |+|-----------------+ |Locconfidence | | | +----------------+|| |type=number | | | || |HAGL | | | || |type=float | | | || |HAGLuncertainty| | | || |type=number | | Das, ed., et al. Expires January 15, 2013 [Page 16] Internet-Draft Device to Database Protocol July 2012 | || |Antennatype | | | || |type=int | | | || |Geolocationcode| | | || |type=string | | | || |---------------+ | | || | | | ||-----------------+ |----------------+ | | ||Slavedevicellist | |Sdevidentitylist| | | ||type=sdevicearray|--+type=list | | | ||-----------------+ |Sdevserialno | | | || |type=list | | | || |Validity | | | || |type=string | | | || |----------------+ | | || | | | ||-----------------+ |------------+ | | ||Authinformation|-| |Authscheme | | | ||type=authinfo |--+type=string | | | ||-----------------+ |Realm | | | || |type=string | | | || |Nonce | | | || |type=string | | | || |cnonce | | | || |type=string | | | || |qop | | | || |type=string | | | || |------------+ | | ++====================+==================+ | | | | Figure 7: PAWS Data Model 6.1. Data Element Definition Capabilityinfo;type=capability This data element is used to exchange the capability information of the `Master Device` including the regulatory domain information in which the service is requested for. This is a mandatory feature of the protocol operation. However, the list of attributes may depend upon the regulatory domain requirements. Das, ed., et al. Expires January 15, 2013 [Page 17] Internet-Draft Device to Database Protocol July 2012 Protocolinfo;type=proto This data element is used to exchange the protocol information such, as protocol version, message type and the result code. This is a mandatory feature of the protocol operation. Authinformation;type=authinfo This data element is used to exchange authentication information that is required by the server for the client authentication and provide authentication and message integrity of the subsequent messages. This include `Digest Authentication` parameters and it is a mandatory feature of the protocol operation. Devicelocation;type=geo-loc, civic This data element is used to provide the location information of the `Master device` to the database. This is a mandatory feature of the protocol operation and the list of attributes for this element may depend upon the regulatory domain requirements. Deviceowner;type=ownerinfo This data element is used to provide the owner information (as applicable) of the `Master WSD` to the database operator. This is an optional feature of the protocol operation and the list of attributes for this element may depend upon the regulatory domain requirements. Deviceowner;type=operatorinfo This data element is used to provide the operator information (as applicable) of the `Master WSD` to the database operator. This is an optional feature of the protocol operation and the list of attributes for this element may depend upon the regulatory domain requirements. AvailChannellist;type= channelarray This data element is used by the `Master WSD` to query the available channels in a given location and time and by the `WS database` for corresponding response. This is a mandatory feature of the protocol operation and the list of attributes for this element may depend upon the regulatory domain requirements. Das, ed., et al. Expires January 15, 2013 [Page 18] Internet-Draft Device to Database Protocol July 2012 UsedChannellist;type= channelarray This data element is used by the `Master WSD` to notify the channels used to the `WS database`. This is an optional feature of the protocol operation and the list of attributes for this element may depend upon the regulatory domain requirements. Slavedevicellist;type= sdevicearray This data element is used by the `Master WSD` to validate the `Slave WSDs` with the `WS Database`. This is an optional feature of the protocol operation and the list of attributes for this element may depend upon the regulatory domain requirements. 6.2. Attribute Definition Devicetype;type=string The type of the whitespace device is being used (fixed or portable). Additionally, this could include regulatory type name for example, in US FCC, device type can be called as Mode II portable/personal device as mentioned in Section 2. Deviceidentity;type=string The identity of the whitespace devices (Master WSD and Slave WSD). This could be a regulatory domain id (e.g., FCCid in US). Deviceserialno;type=string The manufacturer serial number of WSD (e.g.,Master WSD and Slave WSD). DeviceRAT;type=string This attribute represents the Radio Access Technology (RAT) for the master device. Authority;type=string The regulatory domain where the WS service is needed Protoversion;type=float This attribute represents the Version number of the protocol Das, ed., et al. Expires January 15, 2013 [Page 19] Internet-Draft Device to Database Protocol July 2012 Messagetype;type=string Type of the WS application protocol message. An enumerated type. Allowed messages are INIT-REQ, INIT-RESP, REG-REQ, REG-RESP, AVAIL-CHAN-REQ, AVAIL-CHAN-RESP, USE-CHAN-NOTIFY, USE-CHAN-RESP, DEV-VALID-REQ and DEV-VALID-RESP Resultcode; type=boolean This attribute indicates the result of the message transaction. Errorcode; type=number If Resultcode is 'failure', the value of 'Errorcode' represents a specific reason for failure. Error codes are TBD. Authscheme;type=string The name of the authentication scheme used to authenticate the device at the PAWs layer. Realm;type=string A human readable string identifying the security realm of the authentication scheme. Nonce;type=string A random string data that the server (database) sends to the device. Cnonce;type=string A random string data that the client (device) sends to the server. qop;type=string A string of one or more tokens indicating the `quality of protection` values supported by the server. This is optional per [RFC2617]. Latitude;type=float This attribute represents the location co-ordinate; [RFC3825] based representation including resolution can be used. While disclosing such information, privacy and user preferences are important, [RFC4119] based representation should be used. Das, ed., et al. Expires January 15, 2013 [Page 20] Internet-Draft Device to Database Protocol July 2012 Longitude;type=float This attribute represents the location co-ordinate. [RFC3825] based representation including resolution can be used. Where disclosing such information, privacy and user preferences are important, [RFC4119] based representation should be used. Locuncertainty;type=number This attribute represents the location uncertainty in meters. The value is assumed to be 0 when not provided. Locconfidence;type=number This attribute represents the location confidence in percentage. The value is assumed to be 100 when not provided. HAGL;type=float The antenna height above the ground level or average terrain. HAGLuncertainty;type=float This attribute represents the HAGL Uncertainty in meters. The value is assumed to be 0 when not provided. Antennatype;type=int The identity of antenna used for transmission. The identity of the antenna can be regulatory domain specific. Geolocationcode;type=string A value indicating whether the device location components (latitude, Longitude) have been calculated according to another set of parameters, for example civic address. For example, if geo-coding or reverse geo-coding algorithms are used. Ownername;type=string This attribute represents the name of the device owner. Operatorname;type=string This attribute represents the name of the device operator. Das, ed., et al. Expires January 15, 2013 [Page 21] Internet-Draft Device to Database Protocol July 2012 Address;type=string The civic address of the device owner or operator of the device. Email;type=alphanumeric The email address of the device owner or operator of the device. Phonenumber;type=alphanumeric The phone number of the device owner or the operator of the device. Requesttype;type=allchannels, availableonly This attribute provides the ability for the Master WSD to request either available and unavailable channels or available channels only. When requested as 'allchannels' all available and unavailable channels will be returned. When 'availableonly' is requested, only available channel will be returned. Channelno;type=string The list of channels that are available or selected in a given location and time. Minfreq;type=string The minimum frequency of the indicated channel represented in MHz. Maxfreq;type=string The maximum frequency of the indicated channel represented in MHz. MaxEIRP;type=float Maximum effective radiated power measured in dBW. Datetime;type=string This attribute represents the time that the channel is available until when availability flag is 'True'. When the availability flag is 'False' it indicates when the channel may become available. However, the Master WSD needs to query again after the time expires. The format of this representation is a datetime stamp. Das, ed., et al. Expires January 15, 2013 [Page 22] Internet-Draft Device to Database Protocol July 2012 Duration;type=sequence This attribute represents the time that the channel is available until when availability flag is 'True'. When the availability flag is 'False' it indicates when the channel may become available. However, the Master WSD needs to query again after the time expires. The format of this representation is a sequence of ticks and its units. The value of the Unit can be seconds, minutes or hours. Availability;type=string This attribute indicates the availability of the channel (true or false). Usedchannelno;type=list The list of channels that are used by the Master WSD or its associated slave devices in a given location and time. Sdeviceidentitylist;type=list The list of the slave devices' identity that needs the validation with the database. Sdevserialno;type=list The list of the slave devices' manufacturer serial numbers that needs the validation with the database. vailidity;type=list This attribute indicates the validity of the slave devices (true or false). 7. Example Messages with JSON Encoding The examples in this section show the HTTPS messages that include few PAWs messages. The message is encoded in JSON [JSON] structure. The following example shows the request for a registration. the POST includes the `REG-REQ` object. Das, ed., et al. Expires January 15, 2013 [Page 23] Internet-Draft Device to Database Protocol July 2012 POST/REG_REQ HTTPS/1.1 Host:WSP.example.com:443 Content-Type:application/PAWS+json; charset=utf-8 content length: XX { "Protoversion": "1.0", "messagetype": "REG_REQ", "Authority": "US", "Devicetype": "F", "Deviceidentity": "TTT1234", "Deviceserialno": "01AB23CD45EF", "Latttitude": "40.5414", "Longitude": "-74.4750" "Locuncertainty": "2", "LocConfidence": "95", "HAGL: "25", "HAGLuncertainty": "1", "Antennatype":"MM", "Geolocationcode":"DEFAULT", "Ownername": "XYZ", "Address": "444 Hoes Lane, US, 08854", "Phonenumber": "17326992000", "Email":XYZ@gmail.com" "Operatorname": "XYZ", "Address": "444 Hoes Lane, US, 08854", "Phonenumber": "17326992000", "Email":XYZ@gmail.com" "Authscheme": "DIGEST", "Realm":"PAWS-DDI", "Nonce": "7b52009b64fd0a2a49e6d8a939753077792b0554" "Cnonce":"bd307a3ec329e10a2cff8fb87480823da114f8f4", "qop": "auth" "resp": "4dfb972d427b4100c821d53b8bea9b2c33b74a7e", } The following example shows the response for a registration. the POST includes the `REG-RESP` object. Das, ed., et al. Expires January 15, 2013 [Page 24] Internet-Draft Device to Database Protocol July 2012 POST/REG_RESP HTTPS/1.1 200 OK Server: Example PAWS Date: Fri, 12 June 2012 06:24:27 GMT Expires: Fri, 30, June 2012, 23:59:00, GMT Cache-control : private Content-Type:application/PAWS+json; charset=utf-8 content length: YY { "Protoversion": "1.0", "Messagetype": "REG_RESP", "Authority": "US", "Resultcode": "success", "Authscheme": "DIGEST", "Realm":"PAWS-DDI "Nonce": "7b52009b64fd0a2a49e6d8a939753077792b0554"} "qop": "auth" } The following example shows the available channel request. The POST includes the `AVAIL-CHAN-REQ` object. Das, ed., et al. Expires January 15, 2013 [Page 25] Internet-Draft Device to Database Protocol July 2012 POST/AVAIL-CHAN-REQ HTTPS/1.1 Host:WSP.example.com:443 Content-Type:application/PAWS+json; charset=utf-8 content length: XX { "Protoversion": "1.0", "messagetype": "AVAIL_CHAN_REQ", "Authority": "US", "Devicetype": "F", "Deviceidentity": "TTT1234", "Deviceserialno": "01AB23CD45EF", "Latttitude": "40.5414", "Longitude": "-74.4750" "Locuncertainty": "2", "LocConfidence": "95", "HAGL: " 25", "HAGLuncertainty": "1", "Antennatype":"MM", "Geolocationcode":"DEFAULT", "Requesttype":"allchannels", "Authscheme": "DIGEST", "Realm":"PAWS-DDI", "Nonce": "7b52009b64fd0a2a49e6d8a939753077792b0554" "Cnonce":"bd307a3ec329e10a2cff8fb87480823da114f8f4", "qop": "auth" "resp": "4dfb972d427b4100c821d53b8bea9b2c33b74a7e", } The following example shows the response for available channel request. the POST includes the `AVAIL-CHAN-RESP` object. POST/AVAIL_CHAN_RESP HTTPS/1.1 200 OK Server: Example PAWS Date: Fri, 12 June 2012 06:24:27 GMT Expires: Fri, 12 June, June 2012, 20:30:00, GMT Cache-control : private Content-Type:application/PAWS+json; charset=utf-8 content length: YY { "Protoversion": "1.0", "Messagetype": "AVAIL_CHAN_RESP", "Authority": "US", "Resultcode": "success", Das, ed., et al. Expires January 15, 2013 [Page 26] Internet-Draft Device to Database Protocol July 2012 "Authscheme": "DIGEST", "Realm":"PAWS-DDI "Nonce": "7b52009b64fd0a2a49e6d8a939753077792b0554"} "qop": "auth", "Channellist": [ { "Channelno": 2, "Minfreq": 54, "Maxfreq": 60 "MaxEIRP": 4000, "Datetime": "20120612T235959Z", "Duration": "1440, mins", "Availability": true }, { "Channelno": 3, "Minfreq": 60, "Maxfreq": 66, "MaxEIRP": 0, "Datetime": "20120612T235959Z", "Duration": "1440, mins", "Availability": false }, . . . . { "Channelno": 51, "Minfreq": 692, "Maxfreq": 698, "MaxEIRP": 4000, "Datetime": "20120612T120000Z", "Duration": "720, mins ", "Availability": true } } The following example shows the request for a device validation. the POST includes the `DEV_VALID-REQ` object. Das, ed., et al. Expires January 15, 2013 [Page 27] Internet-Draft Device to Database Protocol July 2012 POST/DEV_VALID_REQ HTTPS/1.1 Host:WSP.example.com:443 Content-Type:application/PAWS+json; charset=utf-8 content length: XX { "Protoversion": "1.0", "messagetype": "DEV-VALID-REQ", "Authority": "US", "Devicetype": "F", "Deviceidentity": "TTT1234", "Deviceserialno": "01AB23CD45EF", "Latttitude": "40.5414", "Longitude": "-74.4750" "Locuncertainty": "2", "LocConfidence": "95", "HAGL: " 25", "HAGLuncertainty": "1", "Antennatype":"MM", "Geolocationcode":"DEFAULT", "ownername": "XYZ", "Address": "444 Hoes Lane, US, 08854", "Phonenumber": "17326992000", "Email":XYZ@gmail.com" "Operatorname": "XYZ", "Address": "444 Hoes Lane, US, 08854", "Phonenumber": "17326992000", "Email":XYZ@gmail.com" "Authscheme": "DIGEST", "Realm":"PAWS-DDI", "Nonce": "7b52009b64fd0a2a49e6d8a939753077792b0554" "Cnonce":"bd307a3ec329e10a2cff8fb87480823da114f8f4", "qop": "auth" "resp": "4dfb972d427b4100c821d53b8bea9b2c33b74a7e" "Sdevicelist": [ "sdevidentity": "1234", "sdevserialno": "4321", "sdevidentity": "5678", "sdevserialno": "8765", "sdevidentity": "91011", "sdevserialno": "11109", } Das, ed., et al. Expires January 15, 2013 [Page 28] Internet-Draft Device to Database Protocol July 2012 The following example shows the response for a device validation. The POST includes the `DEV-VALID-RESP` object. POST/DEV_VALID_RESP HTTPS/1.1 200 OK Server: Example PAWS Date: Fri, 12 June 2012 06:24:27 GMT Expires: Fri, 30, June 2012, 23:59:00, GMT Cache-control : private Content-Type:application/PAWS+json; charset=utf-8 content length: YY { Protoversion": "1.0", "Messagetype": "DEV_VALID_RESP", "Authority": "US", "Resultcode": "success", "Authscheme": "DIGEST", "Realm":"PAWS-DDI "Nonce": "7b52009b64fd0a2a49e6d8a939753077792b0554"} "qop": "auth", "Sdevicelist": [ "sdevidentity": "1234", "sdevserialno": "4321", "Validity": true "sdevidentity": "5678", "sdevserialno": "8765", "Validity": true "sdevidentity": "91011", "sdevserialno": "11109", "Validity": false } 8. The Digest Authentication Scheme This section describes the modifications and clarifications required to apply the HTTP Digest authentication scheme to PAWS. The PAWS scheme usage is almost completely identical to that for HTTP [RFC2617] and in particular SIP [RFC3261] except MD5 is replaced by SHA-1 and with the following differences. Future version may support Das, ed., et al. Expires January 15, 2013 [Page 29] Internet-Draft Device to Database Protocol July 2012 SHA-2 (.e.g., SHA-256, SHA-384 and SHA-512). o The URI and method included in the challenge are empty. Therefore to the calculation of the A2 value for message integrity assurance in the Digest authentication scheme, the hash of the entity-body resolves to the SHA-1 hash of an empty string; H(entity- body)=SHA1(" ") = 654e0aaee80e38636c503629d32225db31a616de o The realm represents one `security realm` and the value can be chosen arbitrarily but the realm field from the challenge must be used in the calculation o The device's serial number should be mapped to `username` and the device's shared secret is mapped to `password`. The shared secret MUST have a binding with the device serial number. This document does not describe on how to establish a shared secret. 9. IANA Considerations TBD 10. Acknowledgements Authors would like to acknowledge Dan Harasty, Anthony Triolo, Joel Halpern and Peter Stanforth for their constructive input and feedback on this document. 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [I-D.ietf-paws-problem-stmt-usecases-rqmts] Probasco, S. and B. Patil, "Protocol to Access White Space database: PS, use cases and rqmts", draft-ietf-paws-problem-stmt-usecases-rqmts-06 (work in progress), July 2012. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, Das, ed., et al. Expires January 15, 2013 [Page 30] Internet-Draft Device to Database Protocol July 2012 June 2002. [RFC3825] Polk, J., Schnizlein, J., and M. Linsner, "Dynamic Host Configuration Protocol Option for Coordinate-based Location Configuration Information", RFC 3825, July 2004. [RFC4119] Peterson, J., "A Presence-based GEOPRIV Location Object Format", RFC 4119, December 2005. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. 11.2. Informative References [FCC] FCC, "Second Memorandum Opinion and Order", FCC 10-174, 2010. [OfCom] OFCom, "Implementing Geolocation: http:// stakeholders.ofcom.org.uk/consultations/geolocation/ statement/", September, 2011. [JSON] JSON, "http://www.json.org/". Authors' Addresses Subir Das, ed. Applied Communication Sciences 444 Hoes Lane Piscataway, NJ 08854 U.S.A. Email: sdas at appcomsci dot com John Malyar Telcordia Technologies Inc. 1 Ericsson Drive Piscataway, NJ 08854 U.S.A. Email: jmalyar at telcordia dot com Das, ed., et al. Expires January 15, 2013 [Page 31] Internet-Draft Device to Database Protocol July 2012 Donald Joslyn Spectrum Bridge Inc. 1064 Greenwood Blvd. Lake Mary, FL 32746 U.S.A. Email: d.joslyn at spectrumbridge dot com Das, ed., et al. Expires January 15, 2013 [Page 32]