diff --git a/idl/draft.idl b/idl/draft.idl deleted file mode 100644 index 3d4ba89..0000000 --- a/idl/draft.idl +++ /dev/null @@ -1,56 +0,0 @@ -// This is the WebIDL for the next version under work -// based on discussions on issues #2, #3, #26, #40. -// -// Changes: -// - reintroduce watch (since addEventListener is not allowed to prompt, and -// events vs watches were tricky to implement: too many corner cases -// - reintroduce watch options, filtering on URL patterns, data type etc. -// - replace onmessage event with MessageCallback -// - change send() to pushMessage() - better aligned with semantics -// - add timeout to push options -// - NFCRecord data should be "any" -// - replace scope with URL -// - permission policies changed (in the spec) - -partial interface Navigator { - readonly attribute NFC nfc; -}; - -interface NFC { - Promise requestAdapter(); -}; - -interface NFCAdapter { - Promise pushMessage(NFCMessage message, optional NFCPushOptions options); - - Promise watch(NFCWatchOptions options, MessageCallback callback); - void unwatch(long id); -}; - -callback MessageCallback = void (NFCMessage message, USVString url); - -dictionary NFCWatchOptions { - USVString url; // domain/path or URL pattern - USVString kind; - USVString type; - NFCWatchMode mode; -} - -enum NFCWatchMode { "web-only", "all" }; - -dictionary NFCPushOptions { - NFCDeviceType target; - long timeout; // in ms, default (and max) is 10sec, UAs MAY shorten it -}; - -enum NFCPushTarget { "tag", "peer", "any" }; - -dictionary NFCRecord { - NFCRecordType kind; // based on TNF + JSON - USVString type; // IANA media type, with parameters - any data; // null, string (text, url), Object (json), ArrayBuffer -}; - -typedef sequence NFCMessage; - -enum NFCRecordType { "empty", "text", "url", "json", "opaque" }; diff --git a/idl/web-nfc.idl b/idl/web-nfc.idl index fe3bbe6..3a8c1c1 100644 --- a/idl/web-nfc.idl +++ b/idl/web-nfc.idl @@ -1,3 +1,4 @@ + partial interface Navigator { readonly attribute NFC nfc; }; @@ -6,30 +7,38 @@ interface NFC { Promise requestAdapter(); }; -interface NFCAdapter : EventTarget { - attribute EventHandler onmessage; - Promise send (NFCMessage message, optional NFCSendOptions options); -}; +interface NFCAdapter { + Promise pushMessage(NFCMessage message, optional NFCPushOptions options); + void cancelPush(); -interface NFCMessageEvent : Event { - readonly attribute NFCMessage message; + Promise watch(NFCWatchOptions options, MessageCallback callback); + Promise unwatch(long id); }; -[NoInterfaceObject] -interface NFCMessage { - readonly attribute USVString scope; - readonly attribute sequence data; // (DOMString or URL or Blob or JSON) +dictionary NFCPushOptions { + NFCDeviceType target; + long timeout; // in ms, default (and max) is 10sec, UAs MAY shorten it }; -typedef (DOMString or URL or Blob or JSON) NFCData; +enum NFCPushTarget { "tag", "peer", "any" }; -enum NFCTarget { - "tag", - "peer", - "any" -}; +dictionary NFCWatchOptions { + USVString url; // domain/path or URL pattern + USVString kind; + USVString type; + NFCWatchMode mode; +} -dictionary NFCSendOptions { - NFCTarget target; +enum NFCWatchMode { "web-only", "all" }; + +callback MessageCallback = void (NFCMessage message, USVString url); + +dictionary NFCRecord { + NFCRecordType kind; // based on TNF + JSON + USVString type; // IANA media type, with parameters + any data; // null, string (text, url), Object (json), ArrayBuffer }; +typedef sequence NFCMessage; + +enum NFCRecordType { "empty", "text", "url", "json", "opaque" }; diff --git a/index.html b/index.html index 1d23c18..278be0f 100644 --- a/index.html +++ b/index.html @@ -14,7 +14,7 @@ publishDate: "", previousPublishDate: "", previousMaturity: "", - edDraftURI: "http://w3c.github.io/web-nfc/", + edDraftURI: "https://w3c.github.io/web-nfc/", crEnd: "", editors: [ { name: "Kenneth Rohde Christiansen", company: "Intel", @@ -42,10 +42,18 @@ href: "https://github.com/w3c/web-nfc/commits/gh-pages" }, { value: "Usage scenarios", - href: "http://w3c.github.io/web-nfc/use-cases.html" + href: "https://w3c.github.io/web-nfc/use-cases.html" } ] }, + { + key: "Contributors", + data: [{ + value: "In the github repository", + href: "https://github.com/w3c/web-nfc/graphs/contributors" + } + ] + }, ], localBiblio: { "NFC_SECURITY": { @@ -60,6 +68,24 @@ publisher: "W3C", date: "25 April 2015", }, + "NFC_STANDARDS": { + href: "http://members.nfc-forum.org/specs/spec_list/", + title: "NFC Forum Technical Specifications", + publisher: "NFC Forum", + date: "24 July 2006" + }, + "ISO-639.2": { + href: "https://www.loc.gov/standards/iso639-2/php/code_list.php", + title: "Codes for the Representation of Names of Languages", + publisher: "ISO", + date: "18 March 2014" + }, + "WEBAPPSEC": { + href:"https://w3c.github.io/webappsec/specs/powerfulfeatures", + title: "Secure Contexts", + publisher: "W3C", + date: "17 July 2015" + }, }, }; @@ -84,20 +110,21 @@ NFC is an international standard (ISO/IEC 18092) defining an interface and protocol for simple wireless interconnection of closely coupled devices operating at 13.56 MHz - (see - http://www.nfc-forum.org/specs/spec_list/). + (see + https://www.nfc-forum.org/specs/spec_list/).

- This specification defines an API to manage selected NFC use-cases from web - pages, and to enable new use-cases based on NFC technology. + This document defines an API to enable selected use-cases based on + NFC technology.

- Implementors need to be aware that this specification is considered unstable. - Implementors who are not taking part in the discussions will find the + Implementers need to be aware that this specification is considered + unstable. + Implementers who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on @@ -112,55 +139,114 @@

- This specification defines conformance criteria that apply to a single - product: the user agent that implements the interfaces - it contains. + This document defines conformance criteria that apply to a single + product: the user agent that implements the interfaces it contains.

Implementations that use ECMAScript to implement the APIs defined in - this specification MUST implement them in a manner consistent with the + this document MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as - this specification uses that specification and terminology. + this document uses that specification and terminology.

Terminology

-

+ +

+ The term + browsing context refers to the environment in which + Document objects are + presented to the user. A given browsing context has a single + origin and a single WindowProxy object, but it + can have many Document objects, with their associated + Window objects. The browsing context identifies + the entity which invokes this API, which can be a web app, a + web page, or an + iframe.

- The terms - - event handler and - - event handler event types are defined in [[!HTML5]]. + The term + + incumbent settings object is defined in [[!HTML5]].

- - Promise, and - - JSON.parse are defined in [[!ECMASCRIPT]]. + The term + + secure context is defined in [[!WEBAPPSEC]].

- The algorithms - utf-8 encode, and - - utf-8 decode are defined in [[!ENCODING]]. + The term of executing algorithms + in parallel + is defined in [[!HTML5]].

- - EventInit, + URL + is defined in [[!URL]]. +

+

+ The term + + document base URL is defined in [[!HTML5]]. +

+

+ The term + URL path is defined in [[!URL]]. +

+

+ The term + + origin is defined in [[!HTML5]]. +

+

+ The term + ASCII serialized origin is defined in [[!HTML5]]. +

+

+ The term URL pattern is defined in the + URL patterns section. +

+

+ The term match pattern is defined in the + Match patterns section. +

+ +

+ + DOMString, + + ArrayBuffer, + + BufferSource and + + any + are defined in [[!WEBIDL]]. +

+

+ DOMException, @@ -170,45 +256,57 @@ NotSupportedError, - NotFoundError, and + NotFoundError, + + NetworkError, SecurityError are defined in [[!DOM4]].

- The term web app refers to a Web application, i.e. an application - implemented using Web technologies, and executing within the context of a - Web user agent, e.g. a Web browser or other Web-based runtime - environments. + + Promise, + + JSON and + + JSON.parse + are defined in [[!ECMASCRIPT]].

- The term expressed permission refers to an act by the user, e.g. - via user interface or host device platform features, via which the user - approves the permission of a web app to access the Web NFC API. + The algorithms + utf-8 encode, and + + utf-8 decode are defined in [[!ENCODING]].

- The term obtain permission for a certain operation refers to - obtain expressed permission or to ensure the existence of a - prearranged trust relationship. + IANA media types (formerly known as MIME types) are defined in + RFC2046.

- URL - is defined in [[!URL]]. + The term expressed permission refers to an act by the user, e.g. + via user interface or setting or host device platform features, using which + the user approves the permission of a browsing context to access the + given functionality.

- Blob - is defined in [[!FILEAPI]]. + The term ask for forgiveness refers to some + form of unobtrusive notification that informs the user of an operation + while it is running. + User agents SHOULD provide the user with means to ignore similar future + operations from the same origin and advertise this to the user.

- - DOMString, - - ArrayBuffer, - - BufferSource and - - any - are defined in [[!WEBIDL]]. + The term prearranged trust relationship means that the + user agent has already established a trust relationship for a + certain operation using a platform specific mechanism, so that an + expressed permission from the user is not any more needed. + See also this section in the Security and Privacy document. +

+

+ The term obtain permission for a certain operation indicates + that the user agent has either obtained expressed permission, or + asks for forgiveness, or ensured a + prearranged trust relationship exists.

NFC stands for Near Field Communications, short-range wireless @@ -217,7 +315,8 @@ data exchange formats, and are based on existing radio-frequency identification (RFID) standards, including ISO/IEC 14443 and FeliCa. The NFC standards include ISO/IEC 18092[5] and those defined by the NFC - Forum. See http://www.nfc-forum.org/specs/spec_list/ for a complete listing. + Forum. See https://www.nfc-forum.org/specs/spec_list/ for a complete + listing.

An NFC adapter is the software entity in the underlying @@ -226,7 +325,7 @@ adapters, for instance a built-in one, and one attached via USB.

- An NFC tag is a passive, unpowered NFC device. + An NFC tag is a passive NFC device. The NFC tag is powered by magnetic induction when an active NFC device is in proximity range. An NFC tag contains a single NDEF message. @@ -237,22 +336,25 @@

- An NFC peer is another device, which can interact with other - devices in order to exchange data using NFC. + An NFC peer is an active, powered device, which can interact + with other devices in order to exchange data using NFC. +

+

+ An NFC device is either an NFC peer, or an NFC tag.

An NDEF message encapsulates one or more application-defined - NDEF records. NDEF stands for NFC Forum Data Exchange - Format, a lightweight binary message format. NDEF messages can be stored on - a NFC tag or exchanged between NFC-enabled devices. + NDEF records. NDEF is an abbreviation for NFC Forum + Data Exchange Format, a lightweight binary message format. NDEF messages + can be stored on an NFC tag or exchanged between NFC-enabled devices.

An NDEF record has a maximum payload of 2^32-1 bytes. The record also contains information about the payload size, type, and an optional identifier. NFC Forum standardized a small set of useful data types to be - used in NDEF records, for instance text, URL, media. In addition, - there are record types designed for more complex interactions, such as - Smart Poster, and handover records. + used in NDEF records, for instance text, URL, and binary data such as + media. In addition, there are record types designed for more complex + interactions, such as Smart Poster, and handover records.

Part of the NDEF record is the TNF field, standing for @@ -303,16 +405,52 @@ data and possible actions).

- A Web NFC message is an NDEF message which contains at - least one Web NFC record. + Part of the NDEF record is the NDEF Id field, which may or + may not be present. If present, it contains a maximum 256 octets long + string which is a URL and it is used for identifying the payload, + in an application specific way. In this specification it is used for storing + the ASCII serialized origin of the browsing context which has + written the content. +

+

+ The term NFC content is a synonym for NDEF message, + which can originate either from an NFC tag or an NFC peer. +

+

+ The term Web NFC origin is the ASCII serialized origin + of the browsing context that has written the Web NFC message.

- A Web NFC record is an NDEF record with TNF=4 - (External Type Record), and the type field set to - "urn:nfc:ext:w3.org:webnfc". Further formatting details are - described Data Types. + The Web NFC Id is a special URL stored in the + Web NFC record, and it is used for matching NFC content with + URL patterns specified by listeners. + For more details see the Web NFC Id section.

-

An NFC handover defines NFC Forum Well Known Types and the +

+ A Web NFC record is a special NDEF record which identifies + Web NFC content meant for web pages, rather than generic + NFC content. For a detailed description see the + Web NFC record section. +

+

+ A Web NFC message represents a set of the NDEF records + from a given NDEF message and a special Web NFC record. + For more details see the Web NFC Message + format section. +

+

+ The term Web NFC content denotes all Web NFC messages + contained in an NDEF message. This version of the specification + supports one Web NFC message per NDEF message. +

+

+ The term trusted integrity NFC content refers to an + NDEF message, or an NDEF record, which can be trusted for + data integrity, i.e. the content is not changed by third party between + writing and reading. +

+

+ An NFC handover defines NFC Forum Well Known Types and the corresponding message structure that allows negotiation and activation of an alternative communication carrier, such as Bluetooth or WiFi. The negotiated communication carrier would then be used (separately) to @@ -321,41 +459,29 @@ a television set.

- The term sufficient permission in this document means that a - web app which is invoking the methods of this API has been checked to - comply with the security policies set by the underlying platform and API - implementation in the moment and context of invoking the API method. - Further details are described in - Security and Privacy. -

-

- The term - - document base URL is defined in [[!HTML5]]. -

-

- The term URL scope is introduced in this document for NFC - operations as a sub-domain match to the web app's - document URL, which includes the domain of the calling web app. + An NFC watch is defined in + The watch() method section.

Introduction

- There are three groups of user scenarios for NFC: + In general, there are three groups of user scenarios for NFC:

  • Hold a device close to a passive wireless tag (which could be in the - form of a plastic card) to read and write or overwrite data (in the - case the tag is not read-only, and it is empty or contains a - Web NFC message. + form of a plastic card) to read and write data (if the tag is + not read-only).
  • - Hold two powered devices, e.g. phones or tablets, close to each other - in order to push a Web NFC message from one to the other, or to - initiate a connection using another wireless carrier such as Bluetooth - or WiFi. + Hold two active devices, e.g. phones or tablets, close to each other + in order to push a Web NFC message from one to the other. +
    • +
  • + Hold two active devices, e.g. phones or tablets, close to each other + in order to initiate a connection using another wireless carrier such + as Bluetooth or WiFi.
  • Card emulation
      @@ -385,7 +511,7 @@ As NFC is based on existing RFID standards, many NFC chipsets support reading RFIDs tags, but many of these are only supported by single vendors and not part of the NFC standards. Though certain devices support - reading and writing to these, it is not a goal of this specification to + reading and writing to these, it is not a goal of this document to support proprietary tags or support interoperability with legacy systems.

      @@ -435,59 +561,82 @@ Card emulation mode capabilities also depend on the NFC chip in the device. For payments, a Secure Element is often needed.

      +

      + This document does not aim supporting all possible use cases of NFC + technology, but only a few use cases which are considered relevant to be + used by web pages in browsers, using the browser security model. +

      +
+

Use Cases

- A few Web NFC user scenarios are described in - this document. - These user scenarios can be grouped along - criteria based on security, privacy and feature categories, resulting in - generic flows as follows. + A few Web NFC user scenarios are described in the + Use Cases + document. These user scenarios can be grouped by criteria based on + security, privacy and feature categories, resulting in generic flows as + follows.

Reading NFC tags

  1. - Reading arbitrary tags when no web site is open: - when the user touches a device to an NFC tag when no web site - is currently open, the user agent can open a website to handle - that tag. If multiple websites can handle the tag, a choice is - presented to the user to pick the preferred web site for handling the - tag. - Optionally, web sites have a programmatic means to tell the - user agent they are able and interested to handle - NFC tags of certain type. -
    2. -
  2. - Reading arbitrary tags when a website is currently open: - if the user has a website open and that website has indicated that - it's able to read a set of tags, it might be fine to allow that - website to read a read-only tag that the user taps without presenting - any permission or security dialog to the user. + Reading NFC tags containing a Web NFC message, when a + web page using the Web NFC API is open and in focus. + For instance, a web page instructs the user to tap an NFC tag, and get + information from the tag.
    3. -
-
-

Writing NFC tags

-
  1. - Writing to arbitrary writable tags: the user opens a web page which - can write an NFC tag. This use case SHOULD be restricted or - bound to user permissions for security and privacy reasons. + Reading NFC tags containing other than Web NFC message, + when a web page using the Web NFC API is open and in focus.
  2. - Writing to NFC tags already containing a - Web NFC message: the user agents MAY allow web sites - to write to the tag with using appropriate security dialogs. + Reading NFC tags when no web site using the Web NFC API is + open or in focus. + This use case is not supported in this version of the specification, + and is has low priority for future versions as well.
-

Sending data to NFC peers

+

Writing to NFC tags

+

+ The user opens a web page which can write an NFC tag. The write + operations may be one of the following: +

    +
  1. + Writing to an empty NFC tag. +
    2. +
  2. + Writing to NFC tags which already contains a + Web NFC message with a different Web NFC Id + (i.e. overwriting a web-specific tag). +
    3. +
  3. + Writing to NFC tags which already contains a + Web NFC message with the same Web NFC Id + (i.e. updating own tag). +
    4. +
  4. + Writing to other, writable NFC tags (i.e. overwriting a + generic tag). +
    5. +
+

+

+ Note that an NFC write operation to an NFC tag always involves + also a read operation. +

+
+

Sending data to NFC peer devices

In general, sending data to another Web NFC capable device requires that on the initiating device the user would first have to navigate to a web site. The user would then touch the device against another Web NFC equipped device, and data transfer would occur. On the receiving device - the user agent will dispatch the content to a web site registered - to handle the content and in case of multiple such web sites, the one - chosen by the second user. + the user agent will dispatch the content to an application registered + and eligible to handle the content, and if that application is a browser + which has a web page open and in focus that uses the Web NFC API and has + set up a NFC watch to listen to Web NFC content, then the + content is delivered to the web page through the parameters of an + NFCMessageCallback.

Handover to another wireless connection type

@@ -497,9 +646,10 @@ NFC capable device, and as a result configuration data is sent for a new Bluetooth or WiFi connection, which is then established between the devices. + This use case is not supported in this version of the specification.

- +

Features

High level features for the Web NFC specification include the following:

    -
  1. Support devices with single or multiple NFC adapters.
    2. -
  2. Support communication with active (powered devices such as readers, - phones) and passive (smart cards, tags, etc) devices.
    3. -
  3. Allow users to act on (e.g. read, write or transceive) discovered - NFC devices (passive and active) as well as access the NDEF records - which were read in the process.
    4. -
  4. Allow the user to write a payload via NDEF records to compatible - devices, such as writeable tags, when they come in range.
    5. -
  5. [future] Allow manual connection for various technologies such as - NFC-A and NFC-F depending on secondary device.
    6. -
  6. [future] Allow NFC handover to Bluetooth or WiFi.
    7. -
  7. [future] Allow card emulation with secure element or host card +
  8. + Support devices with single or multiple NFC adapters. + If there are multiple adapters present when requesting an NFC adapter + then the user agent MAY display a dialog for selecting one of them, + or MAY otherwise choose a default adapter based on user settings or + internal policy. +
    9. +
  9. + Support communication with active (powered devices such as readers, + phones) and passive (smart cards, tags, etc) devices. +
    10. +
  10. + Allow users to act on (e.g. read, write or transceive) discovered + NFC devices (passive and active) as well as access the payload + which were read in the process as Web NFC messages. +
    11. +
  11. + Allow users to write a payload via NDEF records to compatible + devices, such as writeable tags, when they come in range, as + Web NFC messages. +
    12. +
  12. + [future] Allow manual connection for various technologies such as + NFC-A and NFC-F depending on the secondary device. +
    13. +
  13. + [future] Allow NFC handover to Bluetooth or WiFi. +
    14. +
  14. + [future] Allow card emulation with secure element or host card emulation.
@@ -543,124 +712,268 @@ The various integrated technologies, wide variety of use cases, and platform integration issues make standardization of NFC for the web a challenge. - Therefore this specification makes a few simplifications in what use cases + Therefore this document makes a few simplifications in what use cases and data types are possible to handle by users of this API:
    -
  • Expose data types already known to web browsers as MIME types.
    • +
  • + Expose data types already known to web browsers as + IANA media types. +
  • Use the web security model.
    • -
  • Implementations encapsulate NDEF record handling and the API +
  • + Implementations encapsulate NDEF record handling and the API exposes only data and control events.

-
- +
+ + -->

Security and Privacy

+

+ The trust model, attacker model, threat model and possible mitigation + proposals for the Web NFC API are presented in the + + Security and Privacy document. This section presents the chosen + security and privacy model through normative requirements to + implementations. +

+ +

Chain of trust

+

+ Web pages using the NFC API are not trusted. + This means that the user needs to be aware of exactly what a web page is + intending to do with NFC at any given moment. Implementations SHOULD + make sure that when the user authorizes an NFC operation, then only that + action is run, without side effects, and exactly in the context and the + number of times the user allows the execution of NFC operations. +

+

+ The content of Web NFC messages is not trusted, unless the user agent + can safely assume that the content has not been change by third parties + between writing and reading it, e.g. in the case of a + prearranged trust relationship can be established. +

+
+ +

Threats

+

+ The main threats are summarized in the + Security and Privacy document. +

+

+ In this specification the following threats are handled with the highest + priority: +

    +
  • + User data privacy : involuntary sharing of user data (such as location, + contacts, personal data, etc) from an NFC-capable device such as a + phone, tablet, or PC. +
    • +
  • + Protecting existing NFC tags from being overwritten by malicious + web pages. +
    • +
+

+
+ +

Permissions and user prompts

+

+ User agents MUST NOT provide Web NFC API access to browsing contexts + without complying with the security policies described in this document. +

+

+ This specification attempts to help minimizing the user prompts needed to + use the Web NFC API and tries to involve implicit policies which can + address the + + threats. + However, this specification does not describe, nor does it + mandate specific user prompting policies. The term obtain permission + is used for acquiring trust for a given operation. +

The Permissions API SHOULD - be supported by user agents for implementing NFC related + be supported by user agents for implementing NFC related [[permissions]]. The required permission name is "nfc". + This allows saving user permissions for a given origin in a + persistent database until revocation.

- User agents MUST NOT provide Web NFC API access - to web apps without the expressed permission of the user. - User agents must acquire consent for [[permissions]] for each call to the - methods of this API, unless a prearranged trust relationship applies. + User agents MUST acquire user consent, i.e. expressed permission for + for using the methods of this API, unless a + prearranged trust relationship applies, or unless an implicit policy + specified in this document allows it, eventually with an + ask for forgiveness indication.

- Permissions that are preserved beyond the current browsing session MUST be - revocable. + The choice of trusting the integrity of NFC content when + used for implementing security policies, for instance the authenticity of + origins saved in the NDEF Id field, or that of the + URL path of the browsing context, and then used for + same-origin or allowed-origins policy by the user agent, SHOULD be based on + prearranged trust relationship (such as encryption and other means), + otherwise the integrity of the content MUST NOT be trusted by user agents + and security policies MUST NOT be based on this.

-

- The Permissions API does - not yet address the issue of revoking permissions. When it will be - addressed, this section will be updated. +

+ All expressed permissions that are preserved beyond the current + browsing session MUST be revocable.

+
+ +

Security policies

- User agents MUST implement the following policies: + User agents MUST implement the following policies:

  1. - User agents MUST implement the Web NFC API to be HTTPS-only. SSL-only - support provides better protection for the user against - man-in-the-middle attacks intended to obtain push registration data. + Only browsing contexts with a defined origin, whose schema + is starting with "https" SHOULD be able to access + NFC content. Browsers MAY ignore this rule for development purposes only.
  2. - In order to use NFC, a website MUST be visible and in focus. For - web pages in background, receiving and sending NFC data MUST be - suspended. + In order to use NFC, the Window object associated with the + active Document of the browsing context using + the Web NFC API MUST be visible and + in focus. This also means that user agents + SHOULD make sure the display is on, and the device is unlocked. + For web pages in background, receiving and sending NFC content + MUST be suspended. +

    + As a consequence, since every access from a browsing context + needs the attention of the user, and since the user must do a physical + gesture of tapping the device to another one in order to use NFC, it + is assumed in this specification that the user has + expressed permission for each NFC operation, provided the + other conditions described in this specification are fulfilled. +

  3. - User agents SHOULD allow Web NFC API access only from top level frames - or frames where the integrity and origin of the content is secure. + When sending (i.e. writing or pushing) Web NFC content, the + ASCII serialized origin of the browsing context requesting + the operation MAY be recorded in each sent NDEF record's + NDEF Id field. + For details see the sending NFC content algorithm.
  4. - Reading arbitrary NFC tags SHOULD always - obtain permission. + When sending (i.e. writing or pushing) Web NFC content, the + URL path of the browsing context requesting + the operation MUST be recorded in each sent NDEF message's + Web NFC record field. + For details see the sending NFC content algorithm. +
    5. +
  5. + When requesting an NFC adapter by the getAdapter + method, or when setting up listeners for reading, or when sending + NFC content, the user agent MAY warn the user that + physical location may be inferred from the act of using NFC by the + origin of the reading browsing context. +
    6. +
  6. + Writing Web NFC content to an NFC tag does NOT need to + obtain permission, if the NFC tag contains + trusted integrity NFC content and the value of the NDEF Id + field is equal to the ASCII serialized origin of the writing + browsing context. + Otherwise the user agent MUST obtain permission for + sending NFC content which overwrites existing information. + See also the sending NFC content algorithm. +
    7. +
  7. + Sending NFC content to an NFC peer does NOT need to + obtain permission, but the previous rules apply. + See the sending NFC content algorithm.
  8. - Writing to an NFC tag, including locking the tag to read-only - MUST always obtain permission. + Making an NFC tag read-only MUST obtain permission, or + otherwise fail.
  9. - Sending data to an NFC peer MUST always obtain permission. + Setting up listeners for reading NFC content SHOULD + obtain permission.
  10. - Listening to NDEF messages MUST always obtain permission. + The process of reading an NDEF messagedoes NOT need to + obtain permission.
  11. - In addition to the previous, only websites with a schema starting with - "https://" SHOULD be able to read NFC tags that is - not empty and does not contain a Web NFC messages. + For Bluetooth and WiFi handover (supported in later versions), + the user SHOULD have to grant access to the secondary API and must be + able to properly understand what they are granting.
  12. - If a Web NFC message contains JSON data, the content - SHOULD be validated by implementations. + The payload data on NFC content is untrusted, and MUST NOT be used + by the user agent to do automatic handling such as opening a web page + with a URL found in an NFC tag, unless the user approves that.
  13. - For Bluetooth and WiFi handover, the user SHOULD have to grant access - to the secondary API and must be able to properly understand what - they are granting. + Since all local content that a web page has access to can be shared with + NFC, the user needs to be clearly aware about the permissions granted + to the web page using the Web NFC API.

+
- -

Data Types

+ +

Data Representation

+

The Web NFC Id

- Web NFC implementations SHOULD use Web NFC messages, which SHOULD - be sufficiently differentiated in order to avoid accidental matching with - a generic NDEF message used in regular NFC tags or between - NFC peers. This is achieved by using an additional - Web NFC record, and in rest using normal NDEF records in - order to compose the NDEF message. + The Web NFC Id SHOULD contain a valid URL according to + [[RFC3986]]. + The scheme of a Web NFC Id MUST always be "https". + The Web NFC Id MUST contain the Web NFC origin, (i.e. the + ASCII serialized origin), optionally followed by the + URL path of the browsing context that has sent the + Web NFC content. +

+
+ +

The format of a Web NFC message

+

+ The format of a Web NFC message is the following: +

+

+
+

The format of a Web NFC record

The format of a Web NFC record is the following. @@ -670,122 +983,210 @@ Type field set to urn:nfc:ext:w3.org:webnfc.

  • - The id field contains the - - ASCII serialized origin which has written the payload. + The NDEF Id field MAY contain the Web NFC origin, although + that is a part of the payload as well.
  • - The payload MAY be empty, or MAY contain implementation specific - contextual data encoded as Base64 ([[RFC4648]]), for instance tokens, - authentication keys etc. + The payload MUST contain the Web NFC Id of the + Web NFC message.

    • -

    Web NFC message payload

    + + +
    +

    The NFCRecord dictionary and + NFCMessage +

    +

    + The content of any Web NFC message is exposed by the following + sequence: +

    +
    + +

    + The content of any NDEF record is exposed by the following + dictionary: +

    +
    +
    NFCDataType kind
    +
    USVString type
    +
    any data
    +
    +

    + The kind + property MUST return the NFCDataType of the + NDEF record. +

    +

    + The type + property MUST return the IANA media type of the NDEF record + payload. +

    +

    + The + data property MUST return the + payload data of the NDEF record with an appropriate ECMAScript + type, which depends on the IANA media type. +

    +
    + +

    The NFCDataType enum

    - The payload of a Web NFC message is represented by using normal - NDEF records. - The following types can be used as payload, i.e. when writing to - NFC tags, sending data to NFC peers, and when reading - NDEF messages. + NFCDataType denotes the data types + supported as NDEF record payload in read and send operations in + this API.

    -
    +
    +
    empty
    +
    text
    +
    url
    +
    json
    +
    opaque

    - NFCData denotes the data types - supported as NDEF record payload in read and send operations in - this API. + The mapping from data types of an NFCRecord to and from + NDEF record types is presented in the algorithmic steps which handle + the data, i.e. the receiving NFC content + algorithm and sending NFC content algorithm.

    +
    + +

    Data mapping

    - The mapping from supported NFCData to - NDEF record types, as used in the send() - method is as follows: + The mapping from data types of an NFCRecord to + NDEF record types, as used in the sending NFC content + algorithm is as follows:

    - + + + - + + + + + + + + + - - + + + + - + + + - + + + - + + +
    NFCDataNFCRecord kindNFCRecord typeNFCRecord data NDEF record type
    DOMString"empty"not usednot usedNFC Forum Empty Type (TNF=0)
    "text"not usedDOMString NFC Forum Well Known Type (TNF=1) with type Text
    URL
      -
    • NFC Forum Well Known Type (TNF=1) with type URI
      • -
    • NFC Forum Well Known Type (TNF=1) with type - Smart Poster -
      • -
    • Absolute URI as defined in [[RFC3986]] (TNF=3)
      • -
    		"url"not usedDOMStringNFC Forum Well Known Type (TNF=1) with type URI
    JSON"json""application/json", "application/*+json" + null or DOMString or Number or + Object + Media-type as defined in [[RFC2046]] (TNF=2) with associated - MIME type "application/json" + IANA media type specified in the type attribute.
    Blob with MIME type"opaque"IANA media typeArrayBuffer or typed array Media-type as defined in [[RFC2046]] (TNF=2)
    Blob without MIME type"opaque""" (empty)ArrayBuffer or typed array NFC Forum External Type (TNF=4)

    - The mapping from NDEF record types to NFCData, - as used for incoming NDEF messages exposed by the - NFCMessageEvent, is as follows: + The mapping from NDEF record types to NFCRecord, + as used for incoming NDEF messages described by the + receiving NFC content algorithm is as + follows:

    - + + + + + + + + + - + + + - + + + - + + + - + + + + + + - - + + + - + urn:nfc:ext:w3.org:webnfc* + + + - + + +
    NDEF record typeNFCDataNFCRecord kindNFCRecord typeNFCRecord data
    NFC Forum Empty Type (TNF=0)"empty"""null
    NFC Forum Well Known Type (TNF=1) with type TextDOMString"text""text/plain"DOMString
    NFC Forum Well Known Type (TNF=1) with type URIURL object"url""text/plain"DOMString
    NFC Forum Well Known Type (TNF=1) with type Smart PosterURL object"url""text/plain"DOMString
    Absolute URI as defined in [[RFC3986]] (TNF=3)URL object"url""text/plain"DOMString
    Media-type as defined in [[RFC2046]] (TNF=2) with associated - MIME type "application/json" + IANA media type "application/json" or + "application/*-json" + "json"The IANA media type used in the NDEF record + null or DOMString or Number or + Object JSON object
    Media-type as defined in [[RFC2046]] (TNF=2)Blob object"opaque"The IANA media type used in the NDEF recordArrayBuffer
    NFC Forum External Type (TNF=4) with type other than - urn:nfc:ext:w3.org:webnfcBlob object"opaque""application/octet-stream"ArrayBuffer
    Any other NDEF record typeBlob object"opaque""application/octet-stream"ArrayBuffer

    - Note that Web NFC records are not exposed to client web apps. + The Web NFC records MUST NOT be exposed to client + browsing contexts.

    @@ -793,7 +1194,7 @@

    Extensions to the Navigator interface

    - The HTML specification defines a + The HTML document defines a Navigator interface [HTML] which this specification extends. @@ -805,7 +1206,7 @@

    The nfc attribute

    When getting the nfc attribute, the - user agent MUST return the NFC object, which provides + user agent MUST return the NFC object, which provides NFC related functionality.

    @@ -817,61 +1218,77 @@

    Implementations MAY expose multiple NFC adapters. By using the - - requestAdapter() method, web apps can obtain an adapter object - providing NFC functionality. - When this method is invoked, the user agent MUST run the following + + requestAdapter() method, the browsing context can obtain an + adapter object providing NFC functionality. + When this method is invoked, the user agent MUST run the following steps:

      -
    1. Let promise be a new Promise object. +
    2. + Let promise be a new Promise object.
    3. Return promise and continue the following steps - asynchronously. + in parallel.
    4. - If sufficient permission has not been granted to use this method, - that is, to use NFC technology from the calling web app, + If the incumbent settings object is not a secure context, then reject promise with "SecurityError", - and terminate these steps. + and terminate this algorithm.
    5. If there is no support for NFC adapter handling functionality in hardware, software, or due to physical incompatibility, then reject promise with - "NotSupportedError", and terminate these steps. + "NotSupportedError", and terminate this algorithm. +
      6. +
    6. Let adapter be null.
      7. +
    7. + If there is a default NFC adapter, set adapter to the + corresponding NFCAdapter object, or if that does not + exist, a new NFCAdapter object which is bound to + work with the default NFC adapter. + Resolve promise with adapter, and terminate these + steps.
    8. - Make a request to the underlying platform to initialize NFC - functionality and enumerate available adapters. If the request fails, + Otherwise, make a request to the underlying platform to enumerate + available NFC adapters. If the request fails, then reject promise with - "NotSupportedError", and terminate these steps. + "NotFoundError", and terminate this algorithm.
    9. - If the request is successful, then select one of the adapters based on - the following algorithm: + If the request is successful, then select one of the NFC adapters + based on the following algorithm:
        -
      1. Let adapter be null.
        2. -
      2. If there is only one adapter, set adapter to that.
        3. +
      3. Let adapter be a new NFCAdapter + object. +
      4. - If there are multiple adapters available, and there is a system or - user setting available with a default adapter being specified, set + If there is only one NFC adapter, then bind adapter to that.
      5. - Otherwise, the user agent MAY pop up a user dialog for - selecting one of the listed adapters, or none of them, and - set adapter to the selected one, if available. + If there are multiple NFC adapters available, and there is + a system or user setting available with a preference to select the + default adapter, then bind adapter to that. +
        6. +
      6. + Otherwise, the user agent MAY pop up a user dialog for + selecting one of the NFC adapter, and bind adapter + to the selected one.
      7. - If no adapter is selected, then reject promise with - "NotFoundError", and terminate these steps. + Otherwise if user prompt is blocked or canceled, select the + first built-in NFC adapter.
      8. - Otherwise if the dialog is blocked or canceled, then select the - first built-in adapter. + If no built-in adapters are found, select the first external + (e.g. USB) NFC adapter. +
        9. +
      9. + Bind adapter to the selected NFC adapter.
        10. -
      10. Otherwise select the first external (e.g. USB) adapter.
    10. @@ -882,206 +1299,1057 @@

    The NFCAdapter interface

    -
    -
    attribute EventHandler onmessage
    -
    Promise<void> send(NFCMessage message, optional NFCSendOptions options)
    +
    +
    Promise<void> pushMessage(NFCMessage message, optional NFCPushOptions options)
    +
    void cancelPush()
    +
    Promise<long> watch(NFCWatchOptions options, MessageCallback callback)
    +
    Promise<void> unwatch(long id)
    -

    - The NFCAdapter interface handles incoming NDEF messages, - exposed by the NFCMessageEvent event, either from an - NFC tag or an NFC peer. By default, listening to this event - SHOULD be disabled. -

    - - -

    Events used with the NFCAdapter interface

    -

    - The following are the event handlers implemented by the - NFCAdapter interface. -

    - - - - - - - - - - - -
    event handlerevent name event type
    onmessagemessageNFCMessageEvent
    - -

    The message event

    -

    - The message event is used for notifying the adapter - object about an NDEF message dispatched to the web app. -

    -
    - - -

    The NFCMessageEvent interface

    -

    - In this specification, NDEF message content is delivered by an - NFCMessageEvent event. -

    -
    -
    readonly attribute NFCMessage message
    +
    +

    - The message - property MUST return the NFCMessage representing the - payload data of the NDEF message. + The NFCAdapter interface provides sending + Web NFC messages to NFC tags or NFC peers within range, + and to set up and cancel NFC watches to handle incoming + Web NFC messages either from an NFC tag or an NFC peer.

    -
    - -

    The NFCMessage interface

    -

    - The content of the NDEF message is exposed by the following - interface: -

    -
    -
    readonly attribute USVString scope
    -
    readonly attribute sequence<any> data
    -
    // (DOMString or URL or Blob or JSON)
    -
    -

    - The scope - property MUST return the URL scope which has written the message. -

    +

    The pushMessage() method

    The - data property MUST return the - payload data of the NDEF message as an array of either - DOMString, or URL object, or Blob - object, or serializable JSON object as a generic Object. + + pushMessage() method is used for saving a NDEF message + to be sent to an NFC tag for writing, or to an NFC peer + device for pushing, next time when they get into proximity range, or until + a timeout expires. At any time there is maximum 2 Web NFC messages + that can be set for sending: one targeted to NFC tags and one for + NFC peers. When there is a Web NFC message set for sending + to any target, then no more messages are accepted to be set until the + current message is sent or a timeout happens.

    -
    -
    -

    The send() method

    +

    The NFCPushTarget enum

    +
    +
    tag
    +
    peer
    +
    any
    +
    +
    + +

    The NFCPushOptions dictionary

    +
    +
    NFCPushTarget target
    +
    unsigned long timeout
    +
    +

    + The target property + denotes the intended target for the pending pushMessage() + operation. The default value is "any". +

    +

    + The timeout property + denotes the timeout for the pending pushMessage() + operation expressed in milliseconds. The default, and maximal value is + 10000, i.e. 10 seconds. After the timeout expires, the + message set for sending is cleared, an error is returned, and a new + Web NFC message can be set for sending. +

    +
    +
    +

    The pushMessage algorithm

    - The - - send() method is used for sending an NDEF message to - either an NFC tag for writing, or to an NFC peer device, - next time when they get into proximity range. - When this method is invoked, the user agent MUST run the following - steps: -

      + When the + + pushMessage() method is invoked, the user agent + MUST run the following sending NFC content algorithm: +
      1. Let promise be a new Promise object.
      2. Return promise and continue the following steps - asynchronously. + in parallel.
      3. - If sufficient permission has not been granted to use this - method, then reject promise with - "SecurityError", and terminate these steps. + If the incumbent settings object is not a + secure context, then reject promise with + "SecurityError", and terminate this algorithm.
      4. If there is no support for the functionality of sending data to an NFC peer in proximity range, or to write data to an NFC tag, then reject promise with - "NotSupportedError", and terminate these steps. + "NotSupportedError", and terminate this algorithm.
      5. - Parse the argument options. If it is undefined - or null, then use the default values. - Otherwise if invalid, then reject promise with - "SyntaxError", and terminate these steps. + Let origin be the origin of the + browsing context invoking this method.
      6. - Parse the argument message.scope. - If the value is undefined, then set scope to - the DOMString describing the document base URL. - If it is invalid in the given platform, or if it is not a - sub-domain match of the document base URL, then reject - promise with "SyntaxError", and terminate - these steps. + Try to obtain permission by applying the following sub-steps: +
          +
        • + If an expressed permission has been granted before for + origin using the + Permissions API, + then continue with step 6. +
          • +
        • + Otherwise, if a prearranged trust relationship exists, + then continue with step 6. +
          • +
        • + Otherwise, try to obtain expressed permission using the + Permissions API. + If a permissions dialog is involved with the user during this, + then the user agent SHOULD notify the user also about that + using NFC for sending content may indirectly reveal the physical + location of the user in certain conditions. + If permission has been granted by the user, then continue with + step 6. +
          • +
        • + Otherwise, reject promise with + "SecurityError", and terminate this algorithm. +
          • +
      7. - For each element in the array message.data, - check the type - to be one of the supported types. - If the value is invalid on the given platform, then reject - promise with "SyntaxError", and - terminate these steps. - For each valid element create an NDEF record. - The implementation choose the best suitable NDEF record format - for the given platform. - Each element in the input array given in message.data - SHOULD map to a separate NDEF record in the NDEF message - to be sent. + Let timeout be the value of options.timeout if + it is defined, or otherwise 10000 (milliseconds).
      8. - Assemble an NDEF message from the NDEF records and an - additional Web NFC record, referred to as output. + Let target be the value of options.target if it + is defined, or otherwise "any".
      9. - Make a request to the underlying platform to send output - to the next device which comes in proximity range. + If the message parameter is not a valid non-empty sequence + of NFCRecord objects, then reject + promise with "SyntaxError", + and terminate this algorithm.
      10. - If after making the request the connection is lost, reject - promise with "TimeoutError". + Let output be the notation for the NDEF message + to be created by an API call to the underlying platform, based on + data provided by these steps.
      11. - If options.target has the value "tag", then - the sending should only happen if an NFC tag is tapped within - a platform specific timeout, otherwise reject promise with - a "TimeoutError" in the case of timeout, or - "InvalidAccessError" if an NFC peer is - tapped instead of a tag. + For each NFCRecord record in the sequence + message, execute the following steps, or make sure + that the underlying platform provides equivalent values to + ndef: +
          +
        • + Let record be the current NFCRecord. +
          • +
        • + Let ndef be the notation for the NDEF record to + be created by an API call to the underlying platform. +
          • +
        • + If record.kind is "empty", then + execute the following steps: +
            +
          • + Set the ndef.TNF field to 0 + (NFC Empty Type record). +
            • +
          • Set all the following fields to 0: + ndef.TYPE_LENGHT, ndef.ID_LENGTH, + ndef.PAYLOAD_LENGTH and thus omit the following + fields from the NDEF record: ndef.TYPE, + ndef.ID, ndef.PAYLOAD. +
            • +
          • + Reset the NFCMessage output to + contain only the current empty record record, + and continue with step 11. +
            • +
          +
          • + +
        • + If record.kind is "text", then + execute the following steps, or make sure + that the underlying platform provides equivalent values to + ndef: +

          + This is to be used when clients specifically want to write an + NDEF Well Known Type Text record. Otherwise clients could + also use "opaque" with an explicit IANA media + type also for text, which has the advantage of better + differentiation, e.g. when using "text/xml", or "text/vcard". +

          +
            +
          • + If record.data is not of type "string" + or "number", then then reject promise + with "SyntaxError", and terminate this algorithm. +
            • +
          • + If record.type is not of type "string" + or if it does not start with "text/", then + reject promise with "SyntaxError", + and terminate this algorithm. + In addition, user agents MAY check that + record.type is a IANA registered media type + for text. If not, then the user agent MAY + reject promise with "SyntaxError", + and terminate this algorithm. +
            • +
          • + Let language be "en". + If record.type does include a lang= + parameter for language encoding (e.g. + "text/plain; lang=fr"), then set language to + the language code extracted from record.type. + If language is not one of the language codes listed + in the IANA language registry + (or [[ISO-639.2]]), + then user agents MAY reject promise with + "SyntaxError", and terminate this algorithm. +

            + Note that lang= is not standard parameter + to IANA media types, but it is used in this specification + in order to maintain compatibility with NFC specifications. +

            +
            • +
          • + Otherwise, +
              +
            1. + Set the ndef.TNF field to 1 (NFC Well Known + Type). +
              2. +
            2. + Set the def.TYPE field to "T" + (value 0x54 in NFC binary encoding). +
              3. +
            3. + Optionally set the ndef.ID field to the + Web NFC origin. +

              + Since the URL path of origin is saved in + the Web NFC record, this step is not required, + and since it occupies space in NFC content, + implementations SHOULD NOT use this step unless they + want to be future-proof about possible variations in + this specification, when writing NFC tags. +

              +
              4. +
            4. + Set the ndef.PAYLOAD field to + record.data encoded according to the + [[NFC_STANDARDS]], NFC Forum Text Record Type + Definition specification: +
                +
              • + The first octet is a status byte containing bit flags. +
                  +
                • + If record.type does include a parameter + for character set for UTF-8 (e.g. + "text/plain; charset=UTF-8;"), then set bit 7 (MSB) + to 0 (meaning UTF-8 encoding), otherwise to 1 + (meaning UTF-16 encoding). +
                  • +
                • Set bit 6 to 0.
                  • +
                • + Set bits 5 to 0 to the length of + language. +
                  • +
                +
                • +
              • + Set the consecutive octets of ndef.PAYLOAD + to the value of language in US-ASCII + encoding. +
                • +
              • + Set the consecutive payload octets to + record.data in the encoding set by the + MSB bit of the first payload octet (by default UTF-16, + or UTF-8 on special request). +
                • +
              +
              5. +
            +
            • +
          +
          • + +
        • + If record.kind is "url", then + execute the map URL to NDEF sub-steps, or make sure + that the underlying platform provides equivalent values to + ndef: +
            +
          • + If record.data is not of type string, + then reject promise with + "SyntaxError", and terminate this algorithm. +
            • +
          • + Otherwise, +
              +
            • + Set the ndef.TNF field to 1 (Well Known Type). +
              • +
            • + Set the ndef.TYPE field to "U" (0x55 in NFC + binary encoding). +
              • +
            • + Optionally set the ndef.ID field to the + Web NFC origin. +
              • +
            • + Set the ndef.PAYLOAD field to + record.data encoded according to the + [[NFC_STANDARDS]], NFC Forum URI Record Type Definition + specification: set the first octet according to the + applicable scheme abbreviation, and set the rest of the + payload bytes to record.data in UTF-8 encoding. +
              • +
            +
            • +
          +
          • + +
        • + If record.kind is "json", then + execute the map JSON to NDEF sub-steps, or make sure + that the underlying platform provides equivalent values to + ndef: +
            +
          • + If record.data is not of type + "string", or "number", or + "object", then reject promise with + "SyntaxError", and terminate this algorithm. +
            • +
          • + If record.type is not + "application/json", or another IANA type for JSON + ("application/<type>+json"), then reject + promise with "SyntaxError", and + terminate this algorithm. +
            • +
          • + Otherwise, +
              +
            • + Set the ndef.TNF field to 2 (Media Type). +
              • +
            • + Set the ndef.TYPE field to + record.type. +
              • +
            • + Optionally set the ndef.ID field to the + Web NFC origin. +
              • +
            • + Set the ndef.PAYLOAD field to + record.data according to the + [[NFC_STANDARDS]], i.e. as an opaque octet stream. +
              • +
            +
            • +
          +
          • + +
        • + If record.kind is "opaque", then + execute the map binary to NDEF sub-steps, or make sure + that the underlying platform provides equivalent values to + ndef: +
            +
          • + If record.data is not of instance of + ArrayBuffer, then reject promise with + "SyntaxError", and terminate this algorithm. +
            • +
          • + The user agent MAY check if record.type is + a valid IANA registered type. If not, then MAY reject + promise with "SyntaxError", and + terminate this algorithm. +
            • +
          • + Otherwise, +
              +
            • + Set the ndef.TNF field to 2 (Media Type). +
              • +
            • + Set the ndef.TYPE field to + record.type. +
              • +
            • + Set the ndef.ID field to the + Web NFC origin. +
              • +
            • + Set the ndef.PAYLOAD field to + record.data according to the + [[NFC_STANDARDS]], i.e. as an opaque octet stream. +
              • +
            +
            • +
          +
          • +
        • + Otherwise, if record.kind is undefined, + then: +
            +
          • + If record.data is instance of + ArrayBuffer, then set record.type to + "application/octet-stream" and execute the + map binary to NDEF + steps. +
            • +
          • + Otherwise, if type of record.data is + "object", then set record.type to + "application/json" and execute the + map JSON to NDEF steps. +
            • +
          • + Otherwise, if type of record.data is + "number" or "string", then + set record.type to "plain/text" and + execute the + map text to NDEF steps. +
            • +
          • + Otherwise reject promise with + "SyntaxError", and terminate this algorithm. +
            • +
          +
          • + +
        • + Add ndef to output. +
          • +
        +
        12. +
      12. + Add a Web NFC record to output to the end of + output by following the + write Web NFC record sub-steps, or make sure that the + underlying platform provides equivalent values to ndef: +
          +
        • + Let ndef be the notation for the NDEF record to + be created by an API call to the underlying platform. +
          • +
        • + Set ndef.TNF to 4 (NDEF External Type). +
          • +
        • + Set ndef.ID to the Web NFC origin. +
          • +
        • + Set ndef.TYPE to + "urn:nfc:ext:w3.org:webnfc". +
          • +
        • + Set ndef.PAYLOAD to the URL path of the + browsing context, encoded in UTF-16. + This is going to be used by NFC watch filters. +

          + In future versions a list of "allowed-origins" may be supported. + It needs more discussions, since there is a security issue with + it. See the + Security and Privacy document. +

          +
          • +
        +
        13. + +
      13. + Make a request to the underlying platform to send output + to the next device which comes in proximity range, and start a timer + timer with timeout. + There MUST be exactly one message set for pushing per calling + browsing context with exactly one associated timer. + This means that every new invocation of the + pushMessage() method replaces the previously set + push message, and also resets the timer associated with it.
      14. - If options.target has the value "peer", then - the sending should only happen if an NFC peer is tapped within - a platform specific timeout, otherwise reject promise with - a "TimeoutError" in the case of timeout, or - "InvalidAccessError" if an NFC tag is - tapped instead of a peer. + If timer expires, reject promise with + "TimeoutError" and terminate this algorithm.
      15. - If options.target has the value "any" (which - is the default value), then the sending should happen if either an - NFC peer or an NFC tag is tapped within a platform - specific timeout, otherwise reject promise with - "TimeoutError". + When an NFC device comes in communication range, +
          +
        • + If options.target has the value "tag", + then the sending should only happen if an NFC tag is + tapped, otherwise reject promise + "InvalidAccessError" and terminate this algorithm. +
          • +
        • + If options.target has the value "peer", + then the sending should only happen if an NFC peer is + tapped, otherwise reject promise with + "InvalidAccessError" and terminate this algorithm. +
          • +
        • + If options.target has the value "any" + (which is the default value), then the sending should happen if + either an NFC peer or an NFC tag is tapped within + the specified timeout. +
          • +
        • + If during the transfer the connection is lost, or an error is + signaled by the underlying platform, then reject + promise with "NetworkError" and + terminate this algorithm. +
          • +
        • + If the transfer is successful, cancel timer and + resolve promise. +
          • +
      16. - If the request is successful, then resolve promise. + If timer is still active, and the + cancelPush() + method is called, reject promise with + "AbortError", as described in the + cancelPush() algorithm. +
        17. +
      17. + If the browsing context loses focus (e.g. the user navigated + to another page), then the pending push messages still exist, and + timer continues to run until timeout, or until the user + switches back the focus and an NFC communication occurs.

      +
    +
    -

    The NFCSendOptions dictionary

    -
    -
    tag
    -
    Only NFC tags are targeted.
    +

    The cancelPush() method

    +

    + The + cancelPush + method is used for resetting the NDEF message set to be pushed next + time an NFC device comes in range. +

    +

    + When the cancelPush() method is invoked, the user agent + MUST run the following algorithm: +

      +
    1. + If the incumbent settings object is not a + secure context, then reject promise with + "SecurityError", and terminate this algorithm. +
      2. +
    2. + If there is no message set for pushing as described in the + pushMessage() algorithm, + or no active timers associated with it, then terminate this algorithm. +

      + This step also covers the case when the timer has already fired, + which also means that the message buffer is invalid, and is to be + replaced by the next invocation of pushMessage(). +

      +
      3. +
    3. + Otherwise, if there is an active timer associated with a message set + to be pushed during the next NFC communication, then execute the + following sub-steps: +
        +
      • + Remove the message set for pushing. +
        • +
      • + Stop and reset the timer associated with + messagePush(). +
        • +
      +
      4. +
    4. + Reject the pending promise in the + pushMessage() algorithm + with "AbortError". +
      5. +
    +

    +
    -
    peer
    -
    Only NFC peers are targeted.
    +

    The watch() method

    +

    + The + + watch() method enables listening to incoming + NDEF messages. +

    +

    + The NFC content to which clients listen can be filtered based on + its data type, and based on the URL path of the + browsing context which has been saved to the Web NFC record + of the NFC content. The latter is matched against + URL patterns used in NFC watches. +

    +

    + A NFC watch is referring to a NFCWatchOptions + filter saved together the information with NFC adapter it belongs + to, and a locally unique identifier which is used for cancellation. + The + receiving NFC algorithm uses NFC watches to match incoming + NFC content. +

    +

    + Multiple consecutive calls to the watch() method from the + same origin create filters which are in OR relationship. +

    +

    + Watch filters are grouped by NFC adapter. +

    +

    Match patterns

    +

    + A match pattern is a string which can contain the + '*' wildcard character. + Match patterns are used primarily for matching IANA media types, for + instance the match pattern 'application/*+json' matches + 'application/calendar+json', but does not match + 'application/json'. The match pattern + '*/*json' matches both. +

    +
    +

    URL patterns

    +

    + A URL pattern is a URL which can contain '*' + characters. Each URL pattern is in the form of +

      +
    • scheme— for example, 'https' or '*'
      • +
    • host — for example, 'www.w3.org' or '*.w3.org'
      • +
    • path — for example, '/*', '/foo*', or '/foo/bar'.
      • +
    +

    +

    + The syntax is the following: + 

    +          <url-pattern> := <scheme>://<host><path>
+          <scheme> := '*' | 'https'
+          <host> := '*' | '*.' <any char except '/' and '*'>+
+          <path> := '/' <any chars>
+
    +

    +

    + Note that '*' has slightly different meaning depending on + whether it is in the scheme, host or path part. + In a scheme '*' will match only the allowed + 'https' scheme. + If the host is '*', then it matches any host. If the + host is e.g. '*.myhost', then it will match the + specified host or any of its subdomains. + In the path part, each '*' matches 0 or more + characters. +

    +

    + For example, '*://*.mydomain.com/*' will match + 'https://services.mydomain.com/myservice1/myapp2/' and + 'https://info.mydomain.com/general/'. +

    +
    -
    any
    -
    Both NFC tags and NFC peers are targeted.
    +

    The NFCWatchMode enum

    +
    +
    web-only
    +
    all
    +

    + The "web-only" value means that only those + NDEF messages are exposed which contain a + Web NFC record, i.e. which are meant for web pages. + This is the default value. +

    +

    + The "all" value means that all NDEF messages + are exposed. +

    +
    -
    -
    NFCTarget target
    +

    The NFCWatchOptions dictionary

    +

    + To describe which messages an application is interested in, the + following dictionary is used: +

    +
    +
    USVString url
    +
    USVString kind
    +
    USVString type
    +
    NFCWatchMode mode

    - The target property - denotes the intended target for the pending send() - operation. The default value is "any". + The url property + denotes the URL pattern which is used for matching the + URL path of the Web NFC message which is stored in the + Web NFC record. + The values null, undefined, and + "" mean that no matching happens.

    -
    -
    -
    +

    + The kind property + denotes the string value which is used for matching the + kind property of each NFCRecord object + in a Web NFC message. + The values null and undefined mean that + no matching happens. +

    +

    + The type property + denotes the match pattern which is used for matching the + type property of each NFCRecord object + in a Web NFC message. + The values null and undefined mean that + no matching happens. The value "" matches missing type + information. +

    +

    + The mode property tells + whether only Web NFC content or any NFC content will be + watched. +

    + 
    +        var watchOptions = {
+          url: "www.w3.org/*",  // all paths from the domain are accepted
+          kind: "json",
+          type: "application/*json"  // all IANA media types dealing with JSON
+        }
+
    + 
    +        var watchOptions = {
+          url: "*://*/info/restaurant/daily-menu/",  // accepted from any domain
+          kind: "opaque",
+          type: "application/octet-stream"
+        }
+
    +
    + +

    The watch() algorithm

    +

    + When the + + watch() method is invoked, the user agent MUST run + the following NFC watch algorithm: +

      +
    1. Let promise be a new Promise object. +
      2. +
    2. + Return promise and continue the following steps + in parallel. +
      3. +
    3. + If the incumbent settings object is not a + secure context, then reject promise with + "SecurityError", and terminate this algorithm. +
      4. +
    4. + If there is no support for the functionality of receiving data from an + NFC peer or NFC tag in proximity range, then reject + promise with "NotSupportedError", and + terminate this algorithm. +
      5. +
    5. + Let origin be the origin of the + browsing context invoking this method. +
      6. +
    6. + If the user has earlier denied permission for origin for + all future calls as well, then reject promise with + "SecurityError", and terminate this algorithm. +
      7. +
    7. + Reading NFC content does not require + expressed permission, but unless there is a + prearranged trust relationship, user agents SHOULD + ask for forgiveness with relevant + information displayed to the user which explains that reading + NFC content may indirectly reveal the physical location of the + user. In addition, if the value of options.mode is + "all", then also include in this information that the + origin is requesting to read all NFC content, not only + those meant for web pages. +
      8. +
    8. + If the user has blocked permission from the + ask for forgiveness + interaction for this origin, then reject promise + with "SecurityError", and terminate this algorithm. +

      + The ask for forgiveness interaction + might show choices like "block now" or "block forever", etc. If the + user has chosen to "block forever" the given origin, it + is the responsibility of the user agent to remember these user + choices for each origin, regardless of which + NFC adapter is used, and consult them on later invocations. +

      +
      9. +
    9. + If the argument options contains invalid values, + reject promise with a "SyntaxError", + and terminate this algorithm. +
      10. +
    10. + If this is the first watch being set up for the current + NFC adapter, make a request to the underlying platform to + listen to NDEF messages. +
      11. +
    11. + If the request fails, then reject promise with + "NotSupportedError" , and terminate this algorithm. +
      12. +
    12. + Otherwise, let watchId be a locally unique number assigned + to options and store them together as a NFC watch. +
      13. +
    13. + Resolve promise with watchId. +
      14. +
    14. + If the browsing context loses focus (e.g. the user navigated + to another page), then the registered watches still SHOULD continue to + exist, but SHOULD become paused, i.e. the user agent SHOULD NOT check + and use them until the focus is regained. +
      15. +
    +

    +
    + + +

    The unwatch() method

    +

    + When the + unwatch() method is invoked, the user agent + MUST run the following steps: +

      +
    1. + Let promise be a new Promise object. +
      2. +
    2. + Return promise and continue the following steps + in parallel. +
      3. +
    3. + If the incumbent settings object is not a + secure context, then reject promise with + "SecurityError", and terminate this algorithm. +
      4. +
    4. + If the parameter id is undefined, then + remove all watches and filters set by successive calls of the + NFC watch() method on the current + NFC adapter. +
      5. +
    5. + Otherwise, if the parameter id matches the local identifier + of one of the previously set up watches, remove the corresponding + watch. +
      6. +
    6. + Otherwise, reject promise with + "NotFoundError", and terminate this algorithm. +
      7. +
    7. + If there are no more watches on the current NFC adapter, then + make a request to the underlying platform to stop listening to + NDEF messages on that adapter. +
      8. +
    8. + Resolve promise. +
      9. +
    +

    +
    +
    +
    +

    The algorithm for receiving and parsing NFC content

    +

    + If there are any NFC watches set up for any NFC adapter, then + user agents MUST listen to NDEF messages, according to step 9 + of the NFC watch algorithm. + When an NDEF message is received by the underlying platform, + user agents MUST run the following algorithm: +

      +
    1. + Let input be the notation for the NDEF message + which has been received by the underlying platform. +
      2. +
    2. +

      + This is a placeholder for a possible future feature. In this step, + implementations MAY check if the Web NFC origin saved in + the Web NFC record of input matches with the + origin of the browsing context. If yes, and also + prearranged trust relationship exists so that + input is trusted integrity NFC content, then + same-origin policies MAY be applied. +

      +
      3. +
    3. +

      + This is a placeholder for a possible future feature. In this step, + implementations MAY check if any of the URL patterns saved + in the Web NFC record match with the origin of the + browsing context. If yes, and also if + prearranged trust relationship exists so that + input is trusted integrity NFC content, then + allowed-origin policies MAY be applied. +

      +
      4. +
    4. + For each NDEF record which is part of input, run the + following sub-steps for parsing NDEF record: +
        +
      • + Let ndef be the notation for the current + NDEF record. The fields of ndef are described by + the [[NFC_STANDARDS]]. +
        • +
      • + Let record be a new NFCRecord object. +
        • +
      • + If ndef.TNF is 0 (NFC Empty Record), then set + record.kind to "empty", + record.type to "", + and record.data to null. +
        • +
      • + If ndef.TNF is 1 (NFC Well Known Type Record), and + ndef.TYPE is "T" (value 0x54 in NFC binary + encoding), then execute the following sub-steps for + parsing NDEF Text record, or make sure that the + underlying platform provides equivalent values to the + record object properties: +
          +
        • Set record.kind to "text".
          • +
        • Set record.type to "text/plain".
          • +
        • + Read the first octet of ndef.PAYLOAD. + Let offset be the value given by bits 5 to 0 of the + first payload octet. +
          • +
        • + Let language be the string defined by the consecutive + offset number of octets, converted from US-ASCII + encoding. Append ";lang=" and then the value of + language to record.type. +
          • +
        • + Set record.data to the string created from the + consecutive ndef.PAYLOAD octets, converted to UTF-16 + encoding. +
          • +
        +
        • +
      • + If ndef.TNF is 1 (NFC Well Known Type Record), and + ndef.TYPE is "U" (value 0x55 in NFC binary + encoding), then execute the following sub-steps for + parsing NDEF URL record, or make sure that the + underlying platform provides equivalent values to the + record object properties: +
          +
        • Set record.kind to "url".
          • +
        • Set record.type to "text/plain".
          • +
        • + Let scheme be the value of the first octet of + ndef.PAYLOAD. +
          • +
        • + If scheme is not 0, then set record.data + to the string obtained from mapping the value of scheme + to the URL scheme as specified in the [[NFC_STANDARDS]] URI + Record Type Definition specification, Section 3.2.2. +
          • +
        • + Set record.data to the UTF-16 string converted from the + octets of ndef.PAYLOAD except the first octet. +
          • +
        +
        • +
      • + If ndef.TNF is 3 (NFC Absolute URI Type record), then + set record.kind to "url", + set record.type to "text/plain" and + set record.data to the string converted from + ndef.PAYLOAD. +
        • +
      • + If ndef.TNF is 2 (NFC Media Type record), then execute the + following sub-steps for parsing NDEF Media record, or make + sure that the underlying platform provides equivalent values to the + record object properties: +
          +
        • + If ndef.TYPE matches the match pattern + "application/*json", then +
            +
          • Set record.kind to "json".
            • +
          • Set record.type to ndef.TYPE.
            • +
          • + Set record.data to the result of converting + ndef.PAYLOAD to string. +

            + The payload SHOULD NOT be evaluated by user agents for + security reasons. +

            +
            • +
          +
          • +
        • + Otherwise, +
            +
          • Set record.kind to "opaque".
            • +
          • Set record.type to ndef.TYPE.
            • +
          • + Set record.data to a new ArrayBuffer + object constructed from the octets of ndef.PAYLOAD. +
            • +
          +
          • +
        +
        • +
      • + If ndef.TNF is 4 (NFC External Type record), or 5 (NFC + Unknown Type record) then execute the following sub-steps, + or make sure that the underlying platform provides equivalent values + to the record object properties: +
          +
        • Set record.kind to "opaque".
          • +
        • + If ndef.TYPE is defined, then set + record.type to that string value, otherwise to + "application/octet-stream. +
          • +
        • + Set record.data to a new ArrayBuffer + object constructed from the octets of ndef.PAYLOAD. +
          • +
        +
        • +
      +
      5. +
    +

    +

    Examples

    @@ -1089,78 +2357,59 @@ This section shows how developers can make use of the various features of this specification.

    - 
    -    navigator.permissions.query({name: 'nfc'}).then((result) => {
-        if (result.status == 'granted') {
-          enableNFCUseCase();  // Do things here.
-        } else if (result.status == 'prompt') {
-          // The user agent will prompt.
-        }
-        // Otherwise don't do anything since it will fail.
-      });
-  
         var adapter = null;
+    var id = null;
     navigator.nfc.requestAdapter().then((nfcAdapter) => {
-      adapter = nfcAdapter;
-      adapter.onmessage = onMessage;
+      id = adapter.watch({}, onMessage);
     };
 
-    function onMessage(event) {
-      console.log("NDEF message received from scope " + event.message.scope);
-      var data = event.message.data;
-
-      if (!data) { // empty tag
-        writeMessageOnTag({data: “Initializing a passive tag”});
+    function onMessage(message, url) {
+      console.log("NDEF message received from URL " + url);
+      if (message[0].kind == 'empty') {
+        adapter.pushMessage([
+         { kind: "text", type: "", data: “Initializing a passive tag”}]);
       }
 
-      if (typeof data == ‘string’) {
-        console.log(“Data is string: “ + data);
-      } else if (data instanceof Blob) {
-        processBlob(data);
-      } else if (data instanceof URL) {
-        console.log(“Data is URL: “ + data.toString());
-      } else if (typeof data == ‘object’) {
-        processJSON(data);
-      }
-    };
-
-    function writeMessageOnTag(msg) {
-        adapter.send(msg, {target: "tag"})
-          .then(() => { console.log("Send was successful")})
-          .catch(() => { console.log("Send failed")});
+      message.forEach((record) => {
+        if (record.kind == "string") {
+          console.log(“Data is string: “ + data);
+        } else if (record.kind == "json") {
+          processJSON(record.data);
+        } else if (record.kind == "url") {
+        console.log(“Data is URL: “ + record.data;
+        } else if (record.kind == "opaque") {
+        processBinary(data);
+      });
     };
 
-    function processBlob(data) {
-        console.log(“Blob size: ” + data.size + “ bytes”);
-        console.log(“Blob type: ” + data.type);
-        var reader = new FileReader();
-        reader.addEventListener(“loadend”, function() {
-          console.log(“Blob data: ” + reader.result);
-          // Now send a response based on the data.
-          adapter.send({data: “Response to blob” })
-            .then(() => { console.log("Send was successful")})
-            .catch(() => { console.log("Send failed")});
-        });
-        reader.readAsText(data);
+    function processBinary(data) {
+      console.log("Binary data we know being a string: ");
+      console.log(String.fromCharCode.apply(null, new Uint16Array(data)));
     };
 
     function processJSON(data) {
-      if (myCondition(data.myKnownProperty)) {
-        adapter.send({data: “Custom data”});
+      var obj = JSON.parse(data);
+      console.log("My data: " + obj.myProperty.toString());
+    };
+
    + 
    +    navigator.nfc.requestAdapter().then((adapter) => {
+        adapter.pushMessage([
+          { kind: "text", type: "", data: “Data meant for peers”}])
+        .then(() => { console.log("Message sent")})
+        .catch(() => {console.log("Send failed, try again.")});
     };
   
         navigator.nfc.requestAdapter().then((adapter) => {
       console.log("Waiting for game state");
-      adapter.onmessage = (event) => {
-        console.log("Game state received from: " + event.message.scope);
-        console.log("Game state: " + event.message.data);
+      adapter.watch({ url: "*://myserver/mygame/*"}, (message, url) => {
+        console.log("Game state received from: " + url;
+        console.log("Game state: " + message.data);
         // Now do some calculations and update the state.
-        adapter.send({ scope: event.message.scope,
-                       data: [ { level: 3, points: 4500, lives: 3 } ] })
+        adapter.pushMessage([ data: { level: 3, points: 4500, lives: 3 } ])
           .then(() => { console.log("Send was successful")})
           .catch(() => { console.log("Send failed")});
       };
@@ -1179,19 +2428,25 @@
     recently closed bugs.
   
    
   
      
-    
    • Changed handling of NFC adapters.
      • 
+    
    • Changed data types and mapping to and from NDEF records.
      • 
     
    • 
-      Removed watches/filters.
+      Changed storage conventions of Web NFC content: changed Web NFC record,
+      made it optional to store origin to the NDEF ID field.
     
      • 
+    
    • Reworked the permissions and user prompting model.
      • 
     
    • 
-      Unified handling of peer push and tag writing.
+      Fixed terminology related issues.
     
      • 
+    
    • Changed send() to pushMessage() and added more options.
      • 
+    
    • Re-added watches/filters, in updated form.
      • 
     
    • 
-      Rewritten mapping data types to NDEF records.
-    
      • 
+      Removed event handling for received data, and replaced with handling it
+      in watches, to avoid side effects in adding event listeners.
     
    • 
-      Added Open Issues section, for summarizing present development topics.
+      Updated existing algorithms related to sending NFC content, and added new
+      algorithms, related to receiving NFC content.
     
      • 
+    
    • Updated the code examples.
      •
    @@ -1212,7 +2467,16 @@ Using service workers and protocol handlers. +
  • + + URL objects. +
    • +
  • + + Simplify process for obtaining permissions. +
    • + This version addresses the issues above, and also other issues.

    @@ -1220,8 +2484,9 @@

    Acknowledgements

    The editors would like to express their gratitude to the former editors - Luc Yriarte and Samuel Ortiz, and also to Don Coleman, Jeffrey Yasskin, - Salvatore Iovene, and Alexander Shalamov for their technical guidance, + Luc Yriarte and Samuel Ortiz, and also to Don Coleman, Anne van Kesteren, + Domenic Denicola, Jonas Sickling, Jeffrey Yasskin, Alexander Shalamov, + Salvatore Iovene, and Rijubrata Bhaumik for their technical guidance, implementation feedback and support.

    diff --git a/security-privacy.html b/security-privacy.html index 4f8c183..2282077 100644 --- a/security-privacy.html +++ b/security-privacy.html @@ -43,6 +43,14 @@ } ] }, + { + key: "Contributors", + data: [{ + value: "In the github repository", + href: "https://github.com/w3c/web-nfc/graphs/contributors" + } + ] + }, ], localBiblio: { "MANIFEST": { @@ -86,6 +94,143 @@ Web NFC specification.

    +

    + URL + is defined in [[!URL]]. +

    +

    + The term + browsing context refers to the environment in which + Document objects are + presented to the user. A given browsing context has a single + origin and a single WindowProxy object, but it + can have many Document objects, with their associated + Window objects. The browsing context identifies + the entity which invokes this API, which can be a web app, a + web page, or an + iframe. +

    +

    + The term + + origin is defined in [[!HTML5]]. +

    +

    + The term + ASCII serialized origin is defined in [[!HTML5]]. +

    +

    + NFC stands for Near Field Communications, short-range wireless + technology operating at 13.56 MHz which enables communication between + devices at a distance less than 10 cm. +

    +

    + An NFC adapter is the software entity in the underlying + platform which provides access to NFC functionality implemented in a + given hardware element (NFC chip). A device may have multiple NFC + adapters, for instance a built-in one, and one attached via USB. +

    +

    + An NFC tag is a passive NFC device. + The NFC tag is powered by magnetic induction when an active NFC + device is in proximity range. An NFC tag contains a single + NDEF message. +

    +

    + An NFC peer is an active, powered device, which can interact + with other devices in order to exchange data using NFC. +

    +

    + An NFC device is either an NFC peer, or an NFC tag. +

    +

    + An NDEF message encapsulates one or more application-defined + NDEF records. NDEF is an abbreviation for NFC Forum + Data Exchange Format, a lightweight binary message format. NDEF messages + can be stored on an NFC tag or exchanged between NFC-enabled devices. +

    +

    + An NDEF record has a maximum payload of 2^32-1 bytes. The record + also contains information about the payload size, type, and an optional + identifier. NFC Forum standardized a small set of useful data types to be + used in NDEF records, for instance text, URL, and binary data such as + media. In addition, there are record types designed for more complex + interactions, such as Smart Poster, and handover records. +

    +

    + Part of the NDEF record is the NDEF Id field, which may or + may not be present. If present, it contains a maximum 256 octets long + string which is a URL and it is used for identifying the payload, + in an application specific way. +

    +

    + The term NFC content is a synonym for NDEF message, + which can originate either from an NFC tag or an NFC peer. +

    +

    + The term Web NFC origin is the ASCII serialized origin + of the browsing context that has written the Web NFC message. +

    +

    + The Web NFC Id is a special URL stored in the + Web NFC record, and it is used for matching NFC content with + URL patterns specified by listeners. + For more details see the Web NFC Id section. +

    +

    + A Web NFC record is a special NDEF record which identifies + Web NFC content meant for web pages, rather than generic + NFC content. For a detailed description see the + Web NFC record section. +

    +

    + A Web NFC message represents a set of the NDEF records + from a given NDEF message and a special Web NFC record. + For more details see the Web NFC Message + format section. +

    +

    + The term Web NFC content denotes all Web NFC messages + contained in an NDEF message. This version of the specification + supports one Web NFC message per NDEF message. +

    +

    + The term trusted integrity NFC content refers to an + NDEF message, or an NDEF record, which can be trusted for + data integrity, i.e. the content is not changed by third party between + writing and reading. +

    + +

    + The key security related definitions are the following. +

    +

    + The term expressed permission refers to an act by the user, e.g. + via user interface or setting or host device platform features, using which + the user approves the permission of a browsing context to access the + given functionality. +

    +

    + The term ask for forgiveness refers to some + form of unobtrusive notification that informs the user of an operation + while it is running. + User agents SHOULD provide the user with means to ignore similar future + operations from the same origin and advertise this to the user. +

    +

    + The term prearranged trust relationship means that the + user agent has already established a trust relationship for a + certain operation using a platform specific mechanism, so that an + expressed permission from the user is not any more needed. + See also the + Prearranged trust relationship section. +

    +

    + The term obtain permission for a certain operation indicates + that the user agent has either obtained expressed permission, or + asks for forgiveness, or ensured a + prearranged trust relationship exists. +

    Introduction

    @@ -99,6 +244,74 @@

    +

    Security and privacy context of NFC

    +

    + Discussions in + issues such as in + Verify security model, + Suggest a permission UI + flow, and + Simplify process for + obtaining permissions make it clear that NFC technology has a few + peculiarities with regards to content handling. In summary, +

      +
    • + The user must make a physical act of tapping with an NFC capable device + in order to use the technology. This action can also be involuntary, + for instance by accidentally placing the NFC capable device in the + proximity of an NFC tag or NFC peer. + Therefore other means are also needed to make sure the NFC operation is + according to the intentions of the user. + For instance, the display MUST be on, the device MUST be unlocked, + the browsing context using the NFC API MUST be visible and in + focus, information about ongoing NFC operation SHOULD be visible (in the + form of icons, information banners, etc). +
      • +
    • + The integrity of an NDEF message cannot be guaranteed, unless the + NFC content is encrypted. Therefore NFC content cannot be + handled using the same-origin policy, since the origin of the + content of an NDEF message cannot be established by means + provided by the NFC standards alone. A URL can be included with + NFC content, but it can be faked or changed by 3rd parties not + using the Web NFC API. +

      + Malicious 3rd parties can write arbitrary URL's into the + NDEF Id field, and provide a prepared attack vector as data to + services which use the Web NFC API as well. + Therefore the Web NFC Id cannot be considered the authentic + origin of the data of the NDEF message. +

      +
      • +
    • + Since user agents cannot uniquely identify NFC tag or + NFC peers, there is no notion of "pairing" in communicating via + NFC. + Therefore each operation needs to obtain permission if required. +
      • +
    • + Also, there is no notion of "session" in communicating via NFC, other + than the physical proximity range maintained by the user. +
      • +
    • + The location of the user using NFC technology for reading NFC tag + from web pages might be indirectly found out, by knowing the location of + the NFC tag, the physical event of reading, and the close + physical proximity which is needed to use NFC. + Also, the location of the user might be disclosed by sending + NFC tags, either by directly sharing the user location (when the + browsing context has access to that), or by sending information + that can be used for inferring the location of the user. + Since both reading and sending NFC content might reveal the + location of the user, user agents SHOULD take into account the + security and privacy measures listed in the + + Geolocation API. +
      • +
    +

    +
    +

    Trust model

    Web pages using the NFC API are not trusted. @@ -119,8 +332,13 @@ The following patterns have been considered:

    • malicious web page and benign user: phishing user data
      • -
    • malicious web page prepared by malicious user: destroying tags
      • -
    • malicious or modified tags prepared for attacking devices.
      • +
    • malicious web page and benign user: phishing user location
      • +
    • + malicious web page prepared by malicious user: web page modifies + existing NFC tag leading to indirect damage through fake identities + and attack vectors +
      • +
    • malicious web page prepared by malicious user: destroying tags.

    @@ -130,7 +348,7 @@ - + - + @@ -163,10 +390,12 @@ and the data read may constitute an attack vector on the user agent. @@ -217,25 +446,35 @@ implement multiple security policies, for example some of the following:
    • - reading is not allowed from generic NFC tags but only from special - Web NFC tags + User agents SHOULD allow Web NFC API access only from top level frames + or frames where the integrity and origin of the content is secure. +
      • +
    • + In order to use NFC, a website MUST be visible and in focus. For + web pages in background, receiving and sending NFC data MUST be + suspended. +
      • +
    • + Reading of generic NFC content is allowed, if the reading page scheme is + https.
    • - reading is allowed from generic tags, if the reading page scheme is - e.g. https + Otherwise, reading of generic NFC content is not allowed, only special + Web NFC content can be read.
    • - writing (updates) allowed only to existing special Web NFC tags where + Writing (pushing) is allowed only with special Web NFC content when the writing page origin fulfills certain conditions.
    • - In order to use NFC, a website MUST be visible and in focus. For - web pages in background, receiving and sending NFC data MUST be - suspended. + The payload data on NFC content is untrusted, and SHOULD NOT be used + by the user agent to do automatic handling such as opening a web page + with a URL found in an NFC tag, unless the user approves that.
    • - User agents SHOULD allow Web NFC API access only from top level frames - or frames where the integrity and origin of the content is secure. + Since all local content that a web page has access to can be shared with + NFC, the user needs to be clearly aware about the permissions granted + to the web page using the Web NFC API.
    The Web NFC API specification may require the existence of some of the @@ -248,14 +487,72 @@

    Security mechanisms

    In order to support security policies concerning the Web NFC API, certain - mechanisms need to be supported in all the implementations, such as: + mechanisms are recommended for the implementations, such as:

      -
    • an identification mechanism for telling apart “Web NFC tags” from - generic NFC tags
      • -
    • a mechanism for conveying implementation specific contextual data - which is not exposed to applications.
      • +
    • + An identification mechanism for telling apart “Web NFC content" from + generic NFC content. +
      • +
    • + A mechanism for conveying implementation specific metadata + which is not exposed to applications. +
      • +
    • + A mechanism for obtaining expressed permission of the user. +
      • +
    • + A mechanism for ask for forgiveness policies. +
      • +
    • + A mechanism for prearranged trust relationship. +

    +

    Prearranged trust relationship

    +

    + In order to obtain permission to a Web NFC function, either an + expressed permission is needed (essentially a user prompt or + setting), or the functionality has such low security and privacy impact that + displaying information about the ongoing operation is considered enough + (also known as ask for forgiveness), or then a + prearranged trust relationship MUST be established by using specific + mechanisms of the underlying platform, and by choices made in the + implementation of the user agent. + A few examples for prearranged trust relationship are given below. +

    +

    + Web apps installed from a store, or web pages installed to home screen (with + [[MANIFEST]]) MAY be considered trusted by the user agent. In this case + the trust concerns the client web page, but not to the date exchanged + through NFC. +

    +

    + For trusting the integrity of the data exchanged via NFC, user agents MAY + use encrypted NFC content with key management based on Public Key + Infrastructure. Key management is out of the scope of the Web NFC + llllspecification. +

    +

    + When the risk of 3rd party native applications modifying and faking tags is + considered a problem deferred to native application stores, just like the + issue whether the user can trust a browser implementation or not, then + in this case user agents MAY make the choice of trusting the + data content of NFC tags and peers, and this MAY be considered a + prearranged trust relationship in the Web NFC API. + In that case, user agents MAY consider the Web NFC Id and + the Web NFC record as trusted information, so that origin based + browser security policies MAY be based on them. + Specifically, user prompting policies MAY be relaxed when the origin + of the browsing context requesting the Web NFC functionality is + equal to the the one saved in the Web NFC Id and optionally when it + matches the URL patterns saved in the access control list of + Web NFC record payload. + This kind of prearranged trust relationship can be applied in the case + when the user agent wants to minimize or eliminate user prompts + involved in obtaining permissions, and is able to mitigate the involved + risks in other ways. +

    +
    ThreatCommentsComments, possible mitigation
    @@ -138,13 +356,22 @@ consent of the user. + The user SHOULD be able to be aware of what data can be shared using + NFC from the given web page. Use permissions and user prompts for accessing personal data, minimize user data exposed to NFC.
    Malicious web page overwrites tags without user consent.Permission and user prompt needed for writing tags. + Make sure the write is additive to previous content. + Or, require permission and user prompt needed for writing tags. + Or, control what tags can be written by a given web page, for instance + a web page can write only a tag which can be connected to its origin. + Or, allow this since tags not meant to be written can be protected + by making them read only. +
    @@ -152,9 +379,9 @@ devices. - Permission/user prompt for writing tags and peers. + The user SHOULD be able to be aware of what data can be shared using + NFC from the given web page. + Use permission/user prompt for writing tags and peers.
    - This is a generic problem with all existing NFC tags; - implementations need security hardening; involuntary touch is low - probability due to short range and critical angle for reading; - it’s easier to attack elsewhere (e.g. WiFi and Bluetooth). + This is a generic problem with all existing NFC tags. + The data is considered application specific. + Implementations need security hardening. + Involuntary touch is low probability due to short range and critical + angle for reading. + It’s easier to attack elsewhere (e.g. WiFi and Bluetooth).