Extension API enterprise.platformKeys.

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
new file mode 100644
index 0000000000000000000000000000000000000000..aac6e626ee6cc55c64bbdddb5dc667bffdf04fc7
--- /dev/null
+++ b/chrome/common/extensions/api/enterprise_platform_keys.idl
@@ -0,0 +1,78 @@
+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Use the <code>chrome.enterprise.platformKeys</code> API to generate
+// hardware-backed keys and to install certificates for these keys. The
+// certificates will be available to the platform and can, for example, be used
+// for TLS authentication and network access.
+[platforms = ("chromeos")]
+namespace enterprise.platformKeys {
+  [nocompile] dictionary Token {
+    // Uniquely identifies this Token. Static IDs are 'user' and 'device',
+    // 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.
+    DOMString id;
+
+    // Implements the WebCrypto's <code>SubtleCrypto</code> interface. The
+    // crypto operations are hardware-backed.
+    [instanceOf = SubtleCrypto] object subtleCrypto;
+  };
+
+  // Invoked by <code>getTokens</code> with 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
+  //     certificate.
+  callback GetCertificatesCallback = void(ArrayBuffer[] certificates);
+
+  // Invoked by importCertificate or removeCertificate when the respective
+  // operation is finished.
+  callback DoneCallback = void();
+
+  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).
+    [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.
+    static void getCertificates(DOMString tokenId,
+                                GetCertificatesCallback callback);
+
+    // Imports |certificate| 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.
+    static void importCertificate(DOMString tokenId,
+                                  ArrayBuffer certificate,

[eroman, 2014/05/19 23:27:45]

Regarding this API...

  * Seems like it would be better to use ArrayBufferView for input. ArrayBuffer
is fine for output, but somewhat inconvenient for input.

  * Are extensions being advised to use Promises? (The pattern of a done
completion callback seems like it could be a Promise instead).

[pneubeck (no reviews), 2014/05/20 09:29:21]

ArrayBufferView itself can't be used (even with adaptions to the idl parser /
schema-generator) because the it's defined as  [NoInterfaceObject].
Instead I would have to use e.g. (ArrayBuffer or Uint8Array).

Uint8Array will require adaptions to the generator, it must create the json
schema-type 'binary'.
I really want to punt this to a follow up.
No, according to the extensions team we shouldn't start a patch work with a few
extension APIs using promises and the majority using callbacks.

[Ryan Sleevi, 2014/05/20 18:04:09]

Are you looked at the old TypedArray spec?

This is fixed in ES6 and HTML - see "JavaScript" under
http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.ht...

"The following helper IDL is used for referring to ArrayBuffer-related types
typedef (Int8Array or Uint8Array or Uint8ClampedArray or
         Int16Array or Uint16Array or Int32Array or Uint32Array or
         Float32Array or Float64Array or DataView) ArrayBufferView"

If we have an old IDL definition, it should be easy to fix.

[pneubeck (no reviews), 2014/05/21 15:01:40]

Cool, that will be helpful to make it look like WebCrypto.
This will still depend on blink and the generator being updated also, so TBD.

+                                  optional DoneCallback callback);
+
+    // Removes |certificate| 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),

[eroman, 2014/05/19 23:27:45]

Ah, you mention my comment from above :)
If you have to pick one, I would go with ArrayBufferView, much more convenient
for users.

Not sure how extension IDLs are compiled, however you can probably achieve the
"or" by adding overloads (that is what we do on the blink side anyhow.

[pneubeck (no reviews), 2014/05/20 09:29:21]

Sadly it's very unclear how to realize the 'or' in this case.
At first both idl types are translated into the identical json-schema types
'binary' with the annotation 'instanceOf:ArrayBuffer' and
'instanceOf:Uint8Array'.
Then the generator produces code ignoring the annotation. Thus this leads to a
collision.
I'll have to figure out with @kalman how to resolve this.

[eroman, 2014/05/20 20:16:51]

I see. So the issue is that extensions use a different IDL generator from Blink
proper for their parameter type validation. My recommendations applied to the
Blink IDL generator, I do not know about the extension one. OK to punt to later
version then.

[pneubeck (no reviews), 2014/05/21 15:01:40]

Yes, sadly we have many different IDL and json parsers and generators.

+    // 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.
+    static void removeCertificate(DOMString tokenId,
+                                  ArrayBuffer certificate,
+                                  optional DoneCallback callback);
+  };
+};