Make enterprise.platformKeys documentation public.

chrome/common/extensions/api/enterprise_platform_keys.idl

Index: chrome/common/extensions/api/enterprise_platform_keys.idl
diff --git a/chrome/common/extensions/api/enterprise_platform_keys.idl b/chrome/common/extensions/api/enterprise_platform_keys.idl
index aac6e626ee6cc55c64bbdddb5dc667bffdf04fc7..be3c37af96ce6388e41010a2d67ea808ba57ced8 100644
--- a/chrome/common/extensions/api/enterprise_platform_keys.idl
+++ b/chrome/common/extensions/api/enterprise_platform_keys.idl
@@ -15,8 +15,13 @@ namespace enterprise.platformKeys {
     // returned by getTokens.
     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 crypto operations are hardware-backed.

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

why is being hardware backed important?

is it always true on all platforms?

[Ryan Sleevi, 2014/06/03 00:02:42]

The cryptographic operations, including key generation, are hardware-backed.

+    // Only non-extractable RSASSA-PKCS1-V1_5 keys with moduloLength upto 2048

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

s/upto/up to

[Ryan Sleevi, 2014/06/03 00:02:42]

modulo/modulus/

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

Done.

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

Done.

+    // can be generated. Each key can be used for signing data at most once.
+    // Keys generated by a certain Token cannot be used with any other Token or
+    // with <code>window.crypto.subtle</code>. The opposite doesn't work either.

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

I don't quite understand what these last 2 sentences mean... it might be because
I'm not sure what the last sentence is saying.

[Ryan Sleevi, 2014/06/03 00:02:42]

Keys generated on a specific token cannot be used with any other Tokens, nor can
they be used with <code>window.crypto.subtle</code>. Equally, Key objects
created with <code>window.crypto.subtle</code> cannot be used with this
interface.

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

Done.

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

Done.

     [instanceOf = SubtleCrypto] object subtleCrypto;
   };
 
@@ -38,6 +43,8 @@ namespace enterprise.platformKeys {
     // 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).
+    // Note that the returned Tokens apply additional restrictions to the
+    // SubtleCrypto interface.

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

what restrictions? can you link to them?

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

Removed. That was rather redundant and misleading as SubtleCrypto wasn't
mentioned before.

     [nocompile] static void getTokens(GetTokensCallback callback);
 
     // Returns the list of all client certificates available from the given
@@ -48,13 +55,11 @@ namespace enterprise.platformKeys {
     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.
@@ -62,12 +67,10 @@ namespace enterprise.platformKeys {
                                   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.