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 [[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 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.

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.

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

Security policies

User agents MUST implement the following policies:

1. 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, 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. 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. 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. 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. 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. 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. Making an NFC tag read-only MUST obtain permission, or otherwise fail.
9. Setting up listeners for reading NFC content SHOULD obtain permission.
10. The process of reading an NDEF messagedoes NOT need to obtain permission.
11. 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. 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. 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 NFCMessage sequence

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

The NFCRecord dictionary

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

NFCRecordType kind

USVString type

any data

The kind property MUST return the NFCRecordType 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 NFCRecordType enum

NFCRecordType denotes the data types supported as NDEF record payload in read and send operations in this API.

empty

text

url

json

opaque

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 data types of an NFCRecord to NDEF record types, as used in the sending NFC content algorithm 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:

The Web NFC records MUST NOT be exposed to client browsing contexts.

The nfc attribute

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

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() method

The 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 for there is maximum 2 Web NFC messages that can be set for sending for an origin: one targeted to NFC tags and one to 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.

When the pushMessage(message, options) 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 in parallel.
3. 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 this algorithm.
5. Let origin be the origin of the browsing context invoking this method.
6. 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. Let options be the second argument.
8. Let timeout be the value of options.timeout if it is defined, or otherwise 10000 (milliseconds).
9. Let target be the value of options.target if it is defined, or otherwise "any".
10. If the message parameter is not a valid non-empty sequence of NFCRecord objects, then reject promise with "SyntaxError", and terminate this algorithm.
11. 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.
12. 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. Set the def.TYPE field to "T" (value 0x54 in NFC binary encoding).
        3. 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).
    • 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).
        • 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.
        • 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.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.
13. 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.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.

14. 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.
15. If timer expires, reject promise with "TimeoutError" and terminate this algorithm.
16. When an NFC device comes in communication range,
    • If 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 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 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.
17. If timer is still active, and the cancelPush() method is called, reject promise with "AbortError", as described in the cancelPush() algorithm.
18. 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 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. 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. 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. Reject the pending promise in the pushMessage() algorithm with "AbortError".

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/'.

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.

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 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() method

The watch(options, callback) 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.

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. Return promise and continue the following steps in parallel.
3. 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 receiving data from an NFC peer or NFC tag in proximity range, then reject promise with "NotSupportedError", and terminate this algorithm.
5. Let origin be the origin of the browsing context invoking this method.
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. 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. 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. If the first argument options contains invalid values, reject promise with a "SyntaxError", and terminate this algorithm.
10. If the second argument callback is not a Function, then reject promise with a "SyntaxError", and terminate this algorithm.
11. 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.
12. If the request fails, then reject promise with "NotSupportedError" , and terminate this algorithm.
13. Otherwise, let watchId be a locally unique number assigned to options and callback and store them together as an NFC watch.
14. Resolve promise with watchId.
15. 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.

The unwatch() method

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

1. Let promise be a new Promise object.
2. Return promise and continue the following steps in parallel.
3. If the incumbent settings object is not a secure context, then reject promise with "SecurityError", and terminate this algorithm.
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. Otherwise, if the parameter id matches the local identifier of one of the previously set up watches, remove the corresponding watch.
6. Otherwise, reject promise with "NotFoundError", and terminate this algorithm.
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. Resolve promise.