Make enterprise.platformKeys documentation public.

Removes TODOs, adds some more important details and an example to the documentation.
Makes the documentation appear on the official developer.chrome.com page.

BUG=364435

Review URL: https://codereview.chromium.org/312503004

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@274591 0039d316-1c4b-4281-b951-d872f2087c98

chrome/common/extensions/api/enterprise_platform_keys.idl

@@ -8,23 +8,35 @@
 // for TLS authentication and network access.
 [platforms = ("chromeos")]
 namespace enterprise.platformKeys {
-  [nocompile] dictionary Token {
-    // Uniquely identifies this Token. Static IDs are 'user' and 'device',
+  [nocompile, noinline_doc] dictionary Token {
+    // Uniquely identifies this <code>Token</code>.
+    // <p>Static IDs are <code>"user"</code> and <code>"device"</code>,
     // referring to the platform's user-specific and the device-wide hardware
     // token, respectively. Any other tokens (with other identifiers) might be
-    // returned by getTokens.
+    // returned by $(ref:enterprise.platformKeys.getTokens).</p>
     DOMString id;
 
-    // Implements the WebCrypto's <code>SubtleCrypto</code> interface. The
-    // crypto operations are hardware-backed.
+    // Implements the WebCrypto's
+    // <a href="http://www.w3.org/TR/WebCryptoAPI/#subtlecrypto-interface">SubtleCrypto</a>
+    // interface. The cryptographic operations, including key generation, are
+    // hardware-backed.
+    // <p>Only non-extractable RSASSA-PKCS1-V1_5 keys with
+    // <code>modulusLength</code> up to 2048 can be generated. Each key can be
+    // used for signing data at most once.</p>
+    // <p>Keys generated on a specific <code>Token</code> cannot be used with
+    // any other Tokens, nor can they be used with
+    // <code>window.crypto.subtle</code>. Equally, <code>Key</code> objects
+    // created with <code>window.crypto.subtle</code> cannot be used with this
+    // interface.</p>
     [instanceOf = SubtleCrypto] object subtleCrypto;
   };
 
   // Invoked by <code>getTokens</code> with the list of available Tokens.
+  // |tokens|: The list of available tokens.
   callback GetTokensCallback = void(Token[] tokens);
 
   // Callback to which the certificates are passed.
-  // |certificates| The list of certificates, each in DER encoding of a X.509
+  // |certificates|: The list of certificates, each in DER encoding of a X.509
   //     certificate.
   callback GetCertificatesCallback = void(ArrayBuffer[] certificates);
 
@@ -34,43 +46,40 @@ namespace enterprise.platformKeys {
 
   interface Functions {
     // Returns the available Tokens. In a regular user's session the list will
-    // always contain the user's token with id 'user'. If a device-wide TPM
-    // token is available it will also contain the device-wide token with id
-    // 'device'. The device-wide token will be the same for all sessions on this
-    // device (device in the sense of e.g. a Chromebook).
+    // always contain the user's token with <code>id</code> <code>"user"</code>.
+    // If a device-wide TPM token is available it will also contain the
+    // device-wide token with <code>id</code> <code>"device"</code>. The
+    // device-wide token will be the same for all sessions on this device
+    // (device in the sense of e.g. a Chromebook).
     [nocompile] static void getTokens(GetTokensCallback callback);
 
     // Returns the list of all client certificates available from the given
     // token. Can be used to check for the existence and expiration of client
     // certificates that are usable for a certain authentication.
-    // |tokenId| The id of a Token returned by <code>getTokens</code>.
-    // |callback| Called back with the list of the available certificates.
+    // |tokenId|: The id of a Token returned by <code>getTokens</code>.
+    // |callback|: Called back with the list of the available certificates.
     static void getCertificates(DOMString tokenId,
                                 GetCertificatesCallback callback);
 
-    // Imports |certificate| to the given token if the certified key is already
-    // stored in this token.
+    // Imports <code>certificate</code> to the given token if the certified key
+    // is already stored in this token.
     // After a successful certification request, this function should be used to
     // store the obtained certificate and to make it available to the operating
     // system and browser for authentication.
-    // TODO: Instead of ArrayBuffer should be (ArrayBuffer or ArrayBufferView),
-    // or at least (ArrayBuffer or Uint8Array).
-    // |tokenId| The id of a Token returned by <code>getTokens</code>.
-    // |certificate| The DER encoding of a X.509 certificate.
-    // |callback| Called back when this operation is finished.
+    // |tokenId|: The id of a Token returned by <code>getTokens</code>.
+    // |certificate|: The DER encoding of a X.509 certificate.
+    // |callback|: Called back when this operation is finished.
     static void importCertificate(DOMString tokenId,
                                   ArrayBuffer certificate,
                                   optional DoneCallback callback);
 
-    // Removes |certificate| from the given token if present.
+    // Removes <code>certificate</code> from the given token if present.
     // Should be used to remove obsolete certificates so that they are not
     // considered during authentication and do not clutter the certificate
     // choice. Should be used to free storage in the certificate store.
-    // TODO: Instead of ArrayBuffer should be (ArrayBuffer or ArrayBufferView),
-    // or at least (ArrayBuffer or Uint8Array).
-    // |tokenId| The id of a Token returned by <code>getTokens</code>.
-    // |certificate| The DER encoding of a X.509 certificate.
-    // |callback| Called back when this operation is finished.
+    // |tokenId|: The id of a Token returned by <code>getTokens</code>.
+    // |certificate|: The DER encoding of a X.509 certificate.
+    // |callback|: Called back when this operation is finished.
     static void removeCertificate(DOMString tokenId,
                                   ArrayBuffer certificate,
                                   optional DoneCallback callback);

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

+<p class="note">
+<strong>Note: </strong>
+This API is only available on Chrome OS and to
+<a href="https://support.google.com/chrome/a/answer/1375694?hl=en">extensions pre-installed by policy</a>.
+</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 data-filename="background.js">
+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(
+                {name : "RSASSA-PKCS1-v1_5"}, 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>

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

+{{+partials.standard_extensions_api api:apis.enterprise_platformKeys intro:intros.enterprise_platformKeys /}}