Add PPAPI interfaces for platform verification.

ppapi/api/private/ppb_platform_verification_private.idl

Index: ppapi/api/private/ppb_platform_verification_private.idl
diff --git a/ppapi/api/private/ppb_platform_verification_private.idl b/ppapi/api/private/ppb_platform_verification_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..68573a3c4c68c79d21dd5df1a49582a396bd4cbf
--- /dev/null
+++ b/ppapi/api/private/ppb_platform_verification_private.idl
@@ -0,0 +1,89 @@
+/* Copyright 2013 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.
+ */
+
+/**
+ * This file defines the API for platform verification. Currently, it only
+ * supports Chrome OS.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  M31 = 0.1
+};
+
+/**
+ * The <code>PPB_PlatformVerification_Private</code> interface allows authorized
+ * services to verify that the underlying platform is trusted. An example of

[dmichael (off chromium), 2013/09/09 15:54:21]

Would it be worthwhile to expand on what you mean by trusted? My understanding
is it isn't really a judgement of quality of the platform or anything, just a
question of whether the platform provides storage (and maybe other services)
that are private to the app. Or something like that.

[DaleCurtis, 2013/09/09 20:49:14]

I believe the current text is sufficient. I'm hesitant to add too many details
which might be platform specific.

+ * a trusted platform is a Chromebook in verified boot mode.

[dmichael (off chromium), 2013/09/09 15:54:21]

s/a Chromebook/ChromeOS
?
since not all ChromeOS devices are Chromebooks

[DaleCurtis, 2013/09/09 20:49:14]

Done.

+ */
+
+interface PPB_PlatformVerification_Private {
+  /**
+   * Create() creates a <code>PPB_PlatformVerification_Private</code> object.
+   *
+   * @pram[in] instance A <code>PP_Instance</code> identifying one instance of
+   * a module.
+   *
+   * @return A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_PlatformVerification_Private</code> if successful, 0 if creation
+   * failed.
+   */
+  PP_Resource Create([in] PP_Instance instance);
+
+  /**
+   * IsPlatformVerification() determines if the provided resource is a
+   * <code>PPB_PlatformVerification_Private</code>.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_PlatformVerification_Private</code>.
+   *
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>PPB_PlatformVerification_Private</code>, <code>PP_FALSE</code> if the
+   * resource is invalid or some type other than
+   * <code>PPB_PlatformVerification_Private</code>.
+   */
+  PP_Bool IsPlatformVerification([in] PP_Resource resource);
+
+  /* Whether the platform can be challenged and is expected to pass.
+   */

[dmichael (off chromium), 2013/09/09 15:54:21]

nit: Please use the same comment format as the other methods.

[DaleCurtis, 2013/09/09 20:49:14]

Done.

+  PP_Bool CanChallengePlatform([in] PP_Resource instance);

[dmichael (off chromium), 2013/09/09 15:54:21]

This doesn't seem strictly necessary. Is this basically an optimization so you
don't have to bother creating a challenge?

[DaleCurtis, 2013/09/09 20:49:14]

Yes, kind of, it avoids both the cost of creating a challenge as well as a
network round trip if challenges are expected to pass.  Additionally the
information necessary to construct the challenge may not be available at the
time a client needs to check if platform challenges can succeed.

Essentially it will allow us to avoid a noticeable playback delay in the most
common case where platform challenges are expected to succeed. It also allows
graceful fallback to alternate protection paths for dev mode machines.

+
+  /**
+   * Requests a platform challenge for a given service id.

[dmichael (off chromium), 2013/09/09 15:54:21]

Do you have any public documentation giving more detail about the challenge to
which you can refer?

[DaleCurtis, 2013/09/09 20:49:14]

For ChromeOS it's just n bits of nonce data; which is what I originally wrote
here.  In the previous patch set ddorwin asked for its removal in order to avoid
platform specific implementation details in the interface.

In a broader sense this is the only public documentation I can find currently:
http://www.chromium.org/developers/design-documents/tpm-usage#TOC-Attesting-D...

+   *
+   * @param[in] service_id A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> containing the service_id for the challenge.
+   *
+   * @param[in] challenge A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the challenge data.

[DaleCurtis, 2013/09/06 21:49:32]

One PPAPI Q I have is whether it's worth having these as array buffers or if
there's a more efficient type for their size -- they'll probably range in length
from 256-512 bytes of non-ascii data.

[dmichael (off chromium), 2013/09/09 15:54:21]

tl;dr:  ArrayBuffer vars seem like the right choice here. 

- PPB_Buffer_Dev would work, but always uses shared memory. That would be
wasteful for such small buffers (wasting handles, requiring creation to go to
the browser to get the shared memory). ArrayBuffer will send the data directly
for small sizes (I can't remember the cutoff...  it was picked through empirical
testing, but it's a lot bigger than the sizes you're talking about).

- String Var would also be a bad choice, since it's required to be valid UTF-8.

- The only reasonable alternative to an ArrayBuffer var would be just a byte
array and size. We use that for interfaces like FileIO where you might already
have a buffer that you want to read from or write to, and allocating and copying
to a separate ArrayBuffer would be a waste. ChallengePlatform isn't called
frequently, and using ArrayBuffer shouldn't add extra copies or allocations
anyway.

[DaleCurtis, 2013/09/09 20:49:14]

Thanks for the detailed answer.

+   *
+   * @param[out] signed_data A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the data signed by the
+   * platform.
+   *
+   * @param[out] signed_data_signature A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_ARRAY_BUFFER</code> that contains the signature of the
+   * signed data block.
+   *
+   * @param[out] platform_key_certificate A <code>PP_Var</code> of type
+   * <code>PP_VARTYPE_STRING</code> that contains the device specific
+   * certificate for the requested service_id.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called after
+   * the platform challenge has been completed. This callback will only run if
+   * the return code is <code>PP_OK_COMPLETIONPENDING</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   */
+  int32_t ChallengePlatform(
+      [in] PP_Resource instance,
+      [in] PP_Var service_id,
+      [in] PP_Var challenge,
+      [out] PP_Var signed_data,
+      [out] PP_Var signed_data_signature,
+      [out] PP_Var platform_key_certificate,
+      [in] PP_CompletionCallback callback);
+};