WebAPI/WebNFC: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
 
(287 intermediate revisions by 7 users not shown)
Line 1: Line 1:
= First iteration: NDEF =
= Introduction =
== Current Status (As to Firefox OS v2.2) ==
* Gecko b2g-nfc meta bug, {{bug|860906}}
* Gecko b2g-secure-element meta bug {{bug|1044428}}
* Gaia meta bug,  {{bug|933640}}
* nfcd meta bug, {{bug|1044425}}
* Gonk
** Use a native daemon nfcd which links to native NFC library. [https://github.com/mozilla-b2g/platform_system_nfcd nfcd github]
* Hardware
** Using Nexus-4/Nexus-5, which uses Broadcom NFC chipset with libnfc-nci library.
** Flame, NXP chipsets with libnfc-nci library.


== Scope ==
== Security Review (By Paul Theriault and Stephanie Ouillon) ==
* https://wiki.mozilla.org/Security/Reviews/B2G/WebNFC
* Security Review for WebNFC: {{bug|749325}}
* Security Review for NFC Payment: {{bug|948280}}
* Security Review for NFC privilege API: {{bug|1095417}}


== Contributors ==
* Gecko Engineers: Arno Puder, Garner Lee, Siddartha Pothapragada, Yoshi Huang, Dimi Lee
* Early Contributors: Markus Neubrand, Philipp von Weitershausen
= Roadmap =
== First iteration: NDEF (Firefox OS v1.3) ==
* meta bug, {{Bug|959692}} - (b2g-NFC-1.3) [meta] FxOS v1.3 NFC feature
* Technologies:
* Technologies:
** Focus on NDEF standard only for now
** Focus on NDEF standard only for now
Line 8: Line 29:
* Capabilities:
* Capabilities:
** Read/write NDEF records on tags
** Read/write NDEF records on tags
** P2P NDEF push/receive
** {{bug|933136}} - [Gecko] NFC onpeerready, onpeerlost callbacks
* Implementation:
* Implementation:
** NDEF-only API available on navigator.mozNfc object
** See {{bug|674741}}
** Discovered NDEF tags are automatically parsed and dispatched to content in the "ndefdiscovered" event on navigator.mozNfc
** NDEF-only API is available on MozNFCTag object.
** Discovered NDEF tags are automatically parsed and dispatched to content in the "nfc-manager-tech-discovered" system message.
** navigator.mozNfc only available to a specific privileged content page (cf. WebTelephony, WebSMS).
** navigator.mozNfc only available to a specific privileged content page (cf. WebTelephony, WebSMS).
** For now, content is expected to do filtering and dispatching to handlers e.g. via WebIntents/WebActions/postMessage
** For now, content is expected to do filtering and dispatching to handlers e.g. via WebActivity.
* Gonk
** {{bug|906579}} - B2G NFC: NFC Daemon for supporting libnfc-nci
* Hardware
** Using Nexus-4, which uses Broadcom NFC chipset with libnfc-nci library.


== Proposed API ==
== Second iteration: Handover and other bug fixes (Firefox OS v1.4) ==
 
* meta bug : {{Bug|949293}} - (b2g-NFC-1.4) [meta] FxOS v1.4 NFC feature
navigator.mozNfc has one event related to NDEF discovery. The "techdiscovered" NFC event will be fired when a new NFC technology is discovered either via reading a tag or receiving it via P2P communication. The event will contain an array of technologies discovered. Calling '''ndefDetails''' will retrieve information, such as the length of the NDEF record, and the maximum size of the NDEF. '''ndefRead''' will read the NDEF record, and return it to the caller. '''ndefWrite''' allows writing a NDEF message to a Tag, subject to storage limits. '''ndefPush''' does a P2P Push of an NDEF formatted message to another NFC enabled device.
* Capabilities:
 
** {{bug|933093}} NFC handover.
  interface nsIDOMMozNfc : nsIDOMEventTarget '''{'''
** {{bug|916863}} - [NFC] NFC support in emulator
 
** NFC Manager API
    [implicit_jscontext] attribute jsval '''ontechdiscovered''';
*** {{Bug|952217}} - [B2G][NFC] Have a separate NFC application API and NFC Manager API
    [implicit_jscontext] attribute jsval '''ontechlost''';
*** {{Bug|959437}} - Refactor NfcManager APIs and implementation details to support sendFile , notifyUserAcceptedP2P and other privileged Nfc operations
 
    /**
    * NDEF Functions
    */
 
    /* Get metadata details of the discovered and connected NDEF message */
    [implicit_jscontext] nsIDOMDOMRequest '''ndefDetails'''();
 
    /* NDEF Read returns an array of NDEF Records consisting of 1 or more elements */
    [implicit_jscontext] nsIDOMDOMRequest '''ndefRead'''();
 
    /* NDEF Write records that is an array of 1 or more records */
    [implicit_jscontext] nsIDOMDOMRequest '''ndefWrite'''(in jsval records);
 
    /* P2P Push NDEF records that is an array of 1 or more records */
    [implicit_jscontext] nsIDOMDOMRequest '''ndefPush'''(in jsval records);
 
    /**
    * NFCA functions (future)
    */
 
    [implicit_jscontext] nsIDOMDOMRequest '''nfcATagDetails'''();
 
    [implicit_jscontext] nsIDOMDOMRequest '''nfcATagTransceive'''(in jsval params);
 
    /**
    * Generic tag/tech functions
    */
 
    [implicit_jscontext] nsIDOMDOMRequest '''connect'''(in unsigned long techType);
 
    [implicit_jscontext] nsIDOMDOMRequest '''close'''();
 
  '''}''';
 
NDEF records contain a bunch of metadata and a payload that is exposed as a string.
 
  interface nsIDOMNdefRecord : nsISupports '''{'''
 
    /**
    * Type Name Field (3-bits) - Specifies the NDEF record type in general.
    * tnf_empty: 0x00
    * tnf_well_known: 0x01
    * tnf_mime_media: 0x02
    * tnf_absolute_uri: 0x03
    * tnf_external type: 0x04
    * tnf_unknown: 0x05
    * tnf_unchanged: 0x06
    * tnf_reserved: 0x07
    */
    readonly attribute octet '''tnf''';
 
    /**
    * type - Describes the content of the payload. This can be a mime type.
    */
    readonly attribute DOMString '''type''';
 
    /**
    * id - Identifer is application dependent.
    */
    readonly attribute DOMString '''id''';
 
    /**
    * payload - Binary data blob. The meaning of this field is application dependent.
    */
    readonly attribute jsval '''payload''';
  '''}''';
 
== NDEF Connect Example ==
 
To establish a NFC session, all operations require an initial connect, as it selects the technology to use for subsequent operations until disconnect.
 
  var connectreq = navigator.mozNfc.connect("NDEF");
  connectreq.onsuccess = function() {
    console.log('Connect success!');
  };
  connectreq.onerror = function() {
    console.log('ERROR: Failed to connect.');
  };
 
== NDEF Disconnect Example ==
 
Applications should disconnect when done.
 
  var disconnectreq = navigator.mozNfc.disconnect();
  disconnectreq.onsuccess = function() {
    console.log('Disconnect success!');
  };
  disconnectreq.onerror = function() {
    console.log('ERROR: Failed to disconnect.');
  };
 
== NDEF Details Example ==
 
  var detailreq = navigator.mozNfc.ndefDetails();
  detailreq.onsuccess = function() {
    console.log('Max NDEF Message Length: ' + detailreq.result.maxNdefMsgLen);
  };
  detailreq.onerror = function() {
    console.log('ERROR: Failed to get NDEF details.');
  };
 
== NDEF Read Example ==
 
  navigator.mozNfc.ontechdiscovered = function (event) {
    var tech = event.message.content.tech;
    for (var i in tech) {
      if (tech[i] == 'NDEF') {
        // do connect('NDEF');
        var req = navigator.mozNfc.ndefRead();
        req.onsuccess = function(e) {
          // NDEF Message with array of NDEFRecords
          var records = e.target.result;
          handleNdefDiscovered(records);
        };
        req.onerror = function() {
          console.log('ERROR: Failed to read NDEF on tag.');
        };
      }
    }
  };
 
  function handleNdefDiscovered(records) {
    records.forEach(function (record) {
      console.log("Found a " + record.tnf + " record" +
                " of type " + record.type +
                " with ID " + record.id +
                " and payload " + record.payload);
      // Could dispatch event.message here to other web apps based on MIME type, URI, etc.
    });
  }
 
== NDEF Write Tag Example ==
 
  navigator.mozNfc.ontechdiscovered = function (event) {
    var ndefRecords = [ new NdefRecord(1, "U", "", "\u0000http://mozilla.org") ];
 
    // do connect('NDEF');
    var domreq = navigator.mozNfc.ndefWrite(ndefRecords);
    domreq.onsuccess = function(e) {
      console.log("Successfully wrote records to tag");
    }
    domreq.onerror = function(e) {
      console.log("Write failed!");
    }
  };
 
== NDEF P2P Push Example ==


  var ndefRecords = [ new NdefRecord(1, "U", "", "\u0000http://mozilla.org") ];
== Third iteration: NFC Sharing feature, P2P, emulator support, test cases (Firefox OS v2.0) ==
  // do connect('NDEF')
* meta bug : {{Bug|949293}} - (b2g-NFC-2.0) [meta] FxOS v2.0 NFC feature
  var domreq = navigator.mozNfc.ndefPush(ndefRecords);
* NFC emulator: {{Bug|973133}}
  domreq.onsuccess = function(e) {
* More Gaia unit tests for NFC in apps/system/test/unit/
    console.log("Successfully pushed P2P message");
  }
  domreq.onerror = function(e) {
    console.log("P2P push failed!");
  }


== Application Permissions ==
== Fourth iteration: HCI transaction event (Firefox OS v2.1) ==
* {{bug|979767}}


To use NFC NDEF functions like ndefDetails, ndefRead, ndefWrite, and ndefPush, '''nfc''' permissions are required. Declare them in the application manifest. Currently, only certified applications can use nfc functions.
== Fifth iteration: Secure Element and NFC Privileged API (Firefox OS v2.2) ==
* {{bug|1044428}} b2g-secure-element
** {{Bug|879861}} - NFC Secure Element Support
* {{Bug|1042851}} - (b2g-nfc-privilege) (meta) [NFC] Make NFC APIs available to privileged webapps
** Slide: http://bit.ly/1x7nWp5


  "permissions": {
= Current API =
    "nfc":{}
Check DXR for latest NFC IDL
  }


System level apps declare an additional certified system message permissions, as it fires the nfc-ndef-discovered WebActivities to applications that declare NFC NDEF support:
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNDEFRecord.webidl MozNDEFRecord.webidl]
  "permissions": {
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFC.webidl MozNFC.webidl]
    "nfc": {},
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCPeer.webidl MozNFCPeer.webidl]
    "nfc-manager": {}
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCPeerEvent.webidl MozNFCPeerEvent.webidl]
  }
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCTag.webidl MozNFCTag.webidl]
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCTagEvent.webidl MozNFCTagEvent.webidl]


== MozActivity ==
= Usage of APIs =


Applications that do not have "'''nfc'''" permissions can get NDEF events via activities, and act on the data. The raw NDEF data may be included with the activity, should the application wish to process any special properties of more complex NDEF data structures.
https://developer.mozilla.org/en-US/docs/Web/API/NFC_API


In the application manifest, declare the following in the activities block:
= Application Permissions =


  "nfc-ndef-discovered": {
NFC API has three permissions.
    "filters": {
* '''nfc''', which will be used by privileged applications.
      "type": "uri",
* '''nfc-share''', which will be used by ceritified(internal) applications.
      "uri": { "required":true, "regexp":"/^https?:.{1,16384}$/i" }
* '''nfc-manager', which will be used by System app.
    }
  }


Then implement an activity handler in the application:
'''nfc''' permission could be used for  general tag reading/writing, or sending NDEF to NFC Peer.
'''nfc-share''' could be used to send large file (Blob) to another NFC peer.
'''nfc-manager''' is used to control the RF state of NFC hardware.


window.navigator.mozSetMessageHandler('activity', actHandle);
= Application Dispatch Order =
1) Foreground App, if the callback ontagfound/onpeerfound is set.
2) If the foreground app doesn't register NFC callbacks or cannot process the event, the event will be redirected to System app, and System app will fire a nfc-ndef-discovered MozActivity.


  window.navigator.mozSetMessageHandler('activity', handleActivity);
= NFC on B2G emulator =
 
* See Kami's notes : https://bitbucket.org/kamituel/b2g-notepad/wiki/Using%20emulator
  ...
 
  handleActivity: function yourapp_handleActivity(activity) {
    switch (activity.source.data.type) {
      ...
      case 'uri':
        var uri = this.getUrlFromInput(activity.source.data.uri);
        doSomething(uri);
    }
  }


== Dispatch Order ==
= NFC Resources =
== Reference ==
* Introduction to NFC: http://www.adafruit.com/datasheets/Introduction_to_NFC_v1_0_en.pdf
* NDEF specification: NFCForum-TS-NDEF_1.0.pdf
* Understand NDEF messages : http://developer.nokia.com/Community/Wiki/Inside_NFC:_Understanding_NDEF_message
* NFC forum specifications: http://members.nfc-forum.org/specs/
* Handover specification: NFCForum-TS-ConnectionHandover_1_2.pdf


== Implementation ==
== Similar APIs ==
* W3C NFC API:  http://w3c.github.io/nfc/proposals/common/nfc.html
* Tizen NFC API: https://developer.tizen.org/dev-guide/2.2.0/org.tizen.web.device.apireference/tizen/nfc.html
* Android NFC API: http://developer.android.com/reference/android/nfc/package-summary.html


* See {{bug|674741}}
[[Category:Web APIs]]
* Engineers: Markus Neubrand, Arno Puder, Garner Lee, Siddartha Pothapragada, Philipp von Weitershausen

Latest revision as of 05:16, 16 March 2015

Introduction

Current Status (As to Firefox OS v2.2)

  • Gecko b2g-nfc meta bug, bug 860906
  • Gecko b2g-secure-element meta bug bug 1044428
  • Gaia meta bug, bug 933640
  • nfcd meta bug, bug 1044425
  • Gonk
    • Use a native daemon nfcd which links to native NFC library. nfcd github
  • Hardware
    • Using Nexus-4/Nexus-5, which uses Broadcom NFC chipset with libnfc-nci library.
    • Flame, NXP chipsets with libnfc-nci library.

Security Review (By Paul Theriault and Stephanie Ouillon)

Contributors

  • Gecko Engineers: Arno Puder, Garner Lee, Siddartha Pothapragada, Yoshi Huang, Dimi Lee
  • Early Contributors: Markus Neubrand, Philipp von Weitershausen

Roadmap

First iteration: NDEF (Firefox OS v1.3)

  • meta bug, bug 959692 - (b2g-NFC-1.3) [meta] FxOS v1.3 NFC feature
  • Technologies:
    • Focus on NDEF standard only for now
    • Others (e.g. proprietary MIFARE) to be investigated later.
  • Capabilities:
    • Read/write NDEF records on tags
    • bug 933136 - [Gecko] NFC onpeerready, onpeerlost callbacks
  • Implementation:
    • See bug 674741
    • NDEF-only API is available on MozNFCTag object.
    • Discovered NDEF tags are automatically parsed and dispatched to content in the "nfc-manager-tech-discovered" system message.
    • navigator.mozNfc only available to a specific privileged content page (cf. WebTelephony, WebSMS).
    • For now, content is expected to do filtering and dispatching to handlers e.g. via WebActivity.
  • Gonk
    • bug 906579 - B2G NFC: NFC Daemon for supporting libnfc-nci
  • Hardware
    • Using Nexus-4, which uses Broadcom NFC chipset with libnfc-nci library.

Second iteration: Handover and other bug fixes (Firefox OS v1.4)

  • meta bug : bug 949293 - (b2g-NFC-1.4) [meta] FxOS v1.4 NFC feature
  • Capabilities:
    • bug 933093 NFC handover.
    • bug 916863 - [NFC] NFC support in emulator
    • NFC Manager API
      • bug 952217 - [B2G][NFC] Have a separate NFC application API and NFC Manager API
      • bug 959437 - Refactor NfcManager APIs and implementation details to support sendFile , notifyUserAcceptedP2P and other privileged Nfc operations

Third iteration: NFC Sharing feature, P2P, emulator support, test cases (Firefox OS v2.0)

  • meta bug : bug 949293 - (b2g-NFC-2.0) [meta] FxOS v2.0 NFC feature
  • NFC emulator: bug 973133
  • More Gaia unit tests for NFC in apps/system/test/unit/

Fourth iteration: HCI transaction event (Firefox OS v2.1)

Fifth iteration: Secure Element and NFC Privileged API (Firefox OS v2.2)

Current API

Check DXR for latest NFC IDL

Usage of APIs

https://developer.mozilla.org/en-US/docs/Web/API/NFC_API

Application Permissions

NFC API has three permissions.

  • nfc, which will be used by privileged applications.
  • nfc-share, which will be used by ceritified(internal) applications.
  • nfc-manager', which will be used by System app.

nfc permission could be used for general tag reading/writing, or sending NDEF to NFC Peer. nfc-share could be used to send large file (Blob) to another NFC peer. nfc-manager is used to control the RF state of NFC hardware.

Application Dispatch Order

1) Foreground App, if the callback ontagfound/onpeerfound is set.
2) If the foreground app doesn't register NFC callbacks or cannot process the event, the event will be redirected to System app, and System app will fire a nfc-ndef-discovered MozActivity.

NFC on B2G emulator

NFC Resources

Reference

Similar APIs

Retrieved from "https://wiki.allizom.org/index.php?title=WebAPI/WebNFC&oldid=1062089"