Make enterprise.platformKeys documentation public.

chrome/common/extensions/docs/templates/intros/enterprise_platformKeys.html

+<p class="note">
+<b>Note: </b>

[not at google - send to devlin, 2014/06/02 17:05:16]

consider using <strong> not <b>

[pneubeck (no reviews), 2014/06/03 09:22:21]

Done.

+This API is only available on ChromeOS.

[not at google - send to devlin, 2014/06/02 17:05:16]

mention what it will do on non-ChromeOS platforms

[pneubeck (no reviews), 2014/06/03 09:22:21]

What do you mean? On other platforms it's not available and thus Chrome will not
grant the required permission.

This follows the example of
docs/templates/intros/fileBrowserHandler.html
and notifications.html

[not at google - send to devlin, 2014/06/03 14:44:15]

Oops notifications is wrong.

And good point on the fileBrowserHandler thing; we should probably have a
standard template for chromeos-only actually. Anyhow, what I more meant was that
that could mean that either chrome.enterprise.platformKeys doesn't exist on
non-chromeos or that it throws errors; and I'm pretty sure that it's the latter
of those.

However I think you can hold off changes to this warning because you're going to
need to mention the policy thing at some point once it's implemented.

[pneubeck (no reviews), 2014/06/03 14:48:58]

Shouldn't this behavior be the same as for all APIs for which the extension
wasn't granted the permission?
This behavior should also be determined by the '"platforms": ["chromeos"],'
setting in _permission_features.json?
The "policy thing" (requiring the extension to be pre-installed (aka
force-installed) by policy) is already in place.
I also updated the warning already to mention this requirement.

[not at google - send to devlin, 2014/06/03 15:12:20]

Yes! We can auto-generate it.

But regarding my previous comment, I more mean that failure mechanisms include
the API not existing or the API setting chrome.runtime.lastError. I think that
non-chromeos platforms has the previous behaviour, and non-policy extensions the
latter? A more precise way of phrasing this would be "This API doesn't exist on
non-ChromeOS platforms and will file for non-policy-installed extensions" but
that's a bit wordy. What you have is fine I suppose.
Thanks.

+</p>
+
+<h2 id="usage">Usage</h2>
+
+Typical usage of this API to enroll a client certificate follows these steps: 
+<ul>
+  <li>Get all available tokens using $(ref:enterprise.platformKeys.getTokens).
+  </li>
+  <li>Find the Token with <code>id</code> equal <code>'user'</code>. Use this
+  Token subsequently.</li>
+  <li>Generate a key pair using the <code>generateKey</code> Token method
+  (defined in SubtleCrypto). This will return handle to the key.</li>
+  <li>Export the public key using the <code>exportKey</code> Token method 
+  (defined in SubtleCrypto).
+  <li>Create the signature of the certification request's data using the
+  <code>sign</code> Token method (defined in SubtleCrypto).</li>
+  <li>Complete the certification request and send it to the certification 
+  authority.</li>
+  <li>If a certificate is received, import it using
+  $(ref:enterprise.platformKeys.importCertificate)</li>
+</ul>
+
+<p>
+Here's an example that shows the major API interaction except the building and sending of the certification request:
+</p>
+
+<pre>
+function getUserToken(callback) {
+  chrome.enterprise.platformKeys.getTokens(function(tokens) {
+    for (var i = 0; i < tokens.length; i++) {
+      if (tokens[i].id == 'user') {
+        callback(tokens[i]);
+        return;
+      }
+    }
+    callback(undefined);
+  });
+}
+
+function generateAndSign(userToken) {
+  var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);
+  var algorithm = {
+    name: "RSASSA-PKCS1-v1_5",
+    // RsaHashedKeyGenParams
+    modulusLength: 2048,
+    publicExponent:
+        new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
+    hash: {
+      name: "SHA-1",
+    }
+  };
+  var cachedKeyPair;
+  userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])
+    .then(function(keyPair) {
+            cachedKeyPair = keyPair;
+            return userToken.subtleCrypto.exportKey('spki', keyPair.publicKey);
+          },
+          console.log.bind(console))
+    .then(function(publicKeySpki) {
+            // Build the Certification Request using the public key.
+            return userToken.subtleCrypto.sign(
+                {}, cachedKeyPair.privateKey, data);
+          },
+          console.log.bind(console))
+    .then(function(signature) {
+              // Complete the Certification Request with |signature|.
+              // Send out the request to the CA, calling back
+              // onClientCertificateReceived.
+          },
+          console.log.bind(console));
+}
+
+function onClientCertificateReceived(userToken, certificate) {
+  chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
+}
+
+getUserToken(generateAndSign);
+</pre>