src/chrome/common/extensions/docs/templates/articles/npapi.html

   1 <h1>NPAPI Plugins</h1>
   2
   3 <p>
   4 Leveraging HTML and JavaScript
   5 makes developing new extensions really easy,
   6 but what if you have existing legacy or proprietary code
   7 that you want to reuse in your extension?
   8 You can bundle an NPAPI plugin with your extension,
   9 allowing you to call into native binary code from JavaScript.
  10 </p>
  11
  12 <h2 id="warning">Warning</h2>
  13
  14 <p align="center"><b><a href="http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html">NPAPI is being phased out.</a>
  15 Consider using alternatives.</b></p>
  16
  17 <p align="center"><b>NPAPI is a really big hammer that should only be used when no other approach will work.</b>
  18
  19 <p>Code running in an NPAPI plugin has the full permissions of the current user and is not sandboxed or shielded from malicious input by Google Chrome in any way. You should be especially cautious when processing input from untrusted sources, such as when working with
  20 {{^is_apps}}
  21 <a href="content_scripts#security-considerations">content scripts</a> or
  22 {{/is_apps}}
  23 XMLHttpRequest.
  24
  25 <p>Because of the additional security risks NPAPI poses to users, extensions that use it will require manual review before being accepted in the
  26 <a href="https://chrome.google.com/webstore">Chrome Web Store</a>.</p>
  27
  28 <h2 id="details">Details</h2>
  29
  30 <p>
  31 How to develop an NPAPI plugin is outside the scope of this document.
  32 See <a href="https://developer.mozilla.org/en/Plugins">Mozilla's
  33 NPAPI plugin reference</a> for information on how to do that.
  34 </p>
  35
  36 <p>
  37 Once you have an NPAPI plugin,
  38 follow these steps to get your extension using it.
  39 </p>
  40
  41 <ol>
  42   <li>
  43     Add a section to your extension's <code>manifest.json</code>
  44     that describes where to find the plugin,
  45     along with other properties about it:
  46
  47 <pre data-filename="manifest.json">
  48 {
  49   "name": "My extension",
  50   ...
  51   <b>"plugins": [
  52     { "path": "extension_plugin.dll" }
  53   ]</b>,
  54   ...
  55 }
  56 </pre>
  57
  58     <p>
  59     The "path" property specifies the path to your plugin,
  60     relative to the manifest file.
  61     The "public" property specifies whether
  62     your plugin can be accessed by regular web pages;
  63     the default is false,
  64     meaning only your extension can load the plugin. Add
  65     <code>"public": true</code> to make your plugin accessible on
  66     regular web pages and content scripts. But
  67     <a href="#security-considerations">be careful</a> - any
  68     web page will then be able to call into your plugin.
  69     </p>
  70    </li>
  71
  72    <li>
  73      Create an HTML file that loads your plugin by mime-type.
  74      Assuming your mime-type is "application/x-my-extension":
  75
  76 <pre>
  77 &lt;embed type="application/x-my-extension" id="pluginId"></embed>
  78 &lt;script>
  79   var plugin = document.getElementById("pluginId");
  80   var result = plugin.myPluginMethod();  // call a method in your plugin
  81   console.log("my plugin returned: " + result);
  82 &lt;/script></pre>
  83
  84      <p>
  85      This can be inside a background page
  86      or any other HTML page used by your extension.
  87      If your plugin is "public",
  88      you can even use a content script to programmatically
  89      insert your plugin into a web page.
  90      </p>
  91    </li>
  92 </ol>
  93
  94 <h2 id="security-considerations">Security considerations</h2>
  95
  96 <p>
  97 Including an NPAPI plugin in your extension is dangerous because plugins
  98 have unrestricted access to the local machine.  If your plugin contains
  99 a vulnerability, an attacker might be able to exploit that vulnerability
 100 to install malicious software on the user's machine.  Instead, avoid
 101 including an NPAPI plugin whenever possible.
 102 </p>
 103
 104 <p>
 105 Marking your NPAPI plugin "public" increase the attack surface of your
 106 extension because the plugin is exposed directly to web content, making
 107 it easier for a malicious web site to manipulate your plugin.  Instead,
 108 avoid making your NPAPI plugin public whenever possible.
 109 </p>