Add ContentDecryptionModule interface.

webkit/media/crypto/content_decryption_module.h

Index: webkit/media/crypto/content_decryption_module.h
diff --git a/webkit/media/crypto/content_decryption_module.h b/webkit/media/crypto/content_decryption_module.h
new file mode 100644
index 0000000000000000000000000000000000000000..119a745304dd0a6921eb90f3b66915279ddaa5d1
--- /dev/null
+++ b/webkit/media/crypto/content_decryption_module.h
@@ -0,0 +1,124 @@
+// Copyright (c) 2012 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.
+
+#ifndef WEBKIT_MEDIA_CRYPTO_CONTENT_DECRYPTION_MODULE_H_
+#define WEBKIT_MEDIA_CRYPTO_CONTENT_DECRYPTION_MODULE_H_
+
+#if defined(_MSC_VER)
+typedef unsigned char uint8_t;
+typedef __int64 int64_t;
+#else
+#include <stdint.h>
+#endif
+
+class ContentDecryptionModule;
+
+extern ContentDecryptionModule* CdmCreateInstance();

[scherkus (not reviewing), 2012/08/15 23:26:29]

do these need to be extern C?

[scherkus (not reviewing), 2012/08/15 23:26:29]

what about deleting the instance?

we can't assume the caller has the same memory allocator based on the scheme you
described

[xhwang, 2012/08/16 02:37:43]

Done.

[xhwang, 2012/08/16 02:37:43]

Done.

+extern const char* CdmGetVersion();
+
+enum CdmStatus {

[scherkus (not reviewing), 2012/08/15 23:26:29]

move into CDM class and rename as Status?

[xhwang, 2012/08/16 02:37:43]

Done.

+  kCdmStatusSuccess = 0,
+  kCdmStatusErrorUnknown,
+  kCdmStatusErrorNoKey
+};
+
+// An input buffer can be split into several continuous subsamples.
+// A SubsampleEntry specifies the number of clear and cypher bytes in each

[scherkus (not reviewing), 2012/08/15 23:26:29]

s/cypher/cipher/g

(all src/crypto/ code uses cipher not cypher)

[xhwang, 2012/08/16 02:37:43]

Done. Will fix cypher in src/media later.

+// subsample. For example, the following buffer has three subsamples:
+//
+// |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
+// |    clear1    | cypher1 |  clear2  |   cypher2   | clear3 |    cypher3    |
+//
+// For decryption, all of the cypher bytes in a buffer should be concatenated
+// (in the subsample order) into a single logical stream. The clear bytes should
+// not be considered as part of decryption.
+//
+// Stream to decrypt:   | cypher1 |   cypher2   |    cypher3    |
+// Decrypted stream:    |decryped1|  decryped2  |   decryped3   |
+//
+// After decryption, the decrypted bytes should be copied over the position
+// of the corresponding cypher bytes in the original buffer to form the output
+// buffer. Following the above example, the decrypted buffer should be:
+//
+// |<----- subsample1 ----->|<----- subsample2 ----->|<----- subsample3 ----->|
+// |    clear1    |decryped1|  clear2  |  decryped2  | clear3 |   decryped3   |
+//
+struct SubsampleEntry {
+  int clear_bytes;
+  int cypher_bytes;
+};
+
+struct InputBuffer {
+  uint8_t* data;  // Pointer to the beginning of the input data.
+  int data_size;  // Size (in bytes) of |data|.
+  int data_offset;  // Number of bytes to be discarded before decryption.
+  uint8_t* key_id;  // Key ID to identify the decryption key.

[scherkus (not reviewing), 2012/08/15 23:26:29]

nit: add blank line between each data+size pair (it looks like a big wall of
text at the moment)

[xhwang, 2012/08/16 02:37:43]

Done.

+  int key_id_size;  // Size (in bytes) of |key_id|.
+  uint8_t* iv;  // Initialization vector.
+  int iv_size;  // Size (in bytes) of |iv|.
+  uint8_t* checksum;
+  int checksum_size;  // Size (in bytes) of the |checksum|.
+  struct SubsampleEntry* subsamples;
+  int num_subsamples;  // Number of subsamples in |subsamples|.
+  int64_t timestamp;  // Presentation timestamp in milliseconds.
+  int64_t duration;  // Duration in milliseconds.

[scherkus (not reviewing), 2012/08/15 23:26:29]

AFAIK we no longer care about duration

[xhwang, 2012/08/16 02:37:43]

Will media::Buffer drop the duration?

+};
+
+struct OutputBuffer {
+  uint8_t* data;  // Pointer to the beginning of the output data.
+  int data_size;  // Size (in bytes) of |data|.
+  int64_t timestamp;  // Presentation timestamp in milliseconds.
+  int64_t duration;  // Duration in milliseconds.
+};
+
+class ContentDecryptionModule {
+ public:
+  // Generates a |key_request| as well as a |session_id| given the |init_data|.
+  // The CDM may also extract a |default_url|.
+  // Returns kCdmStatusSuccess if the key request is successfully generated,

[scherkus (not reviewing), 2012/08/15 23:26:29]

s/is/was

[xhwang, 2012/08/16 02:37:43]

Done, here and below.

+  // in which case the callee should have allocated memory for the output

[scherkus (not reviewing), 2012/08/15 23:26:29]

I'm suspicious of this memory allocating business -- it assumes that the
implementor of this CDM stuff (the .so or whatever) uses the same memory
allocator as the caller

i.e., the caller may be using tcmalloc but the .so is using regular Win32 malloc
calls

typical solutions are:
  1) Caller preallocates buffer + passes in
  2) Caller has to return buffers to free
  3) Assume implementor uses chromium code and make this a basic chromium
interface with chromium types

[xhwang, 2012/08/16 02:37:43]

Thank you so much for the suggestions. We were aware of this issue. ddorwin@ has
a plan than can fix this, but we don't have time and test (a working CDM) to try
that now. Added two TODOs to track this.

About 3), even if the implementor uses chromium code, it's still possible that
he/she uses a different compiler than we do, e.g. he/she has a super old
checkout of chromium?

[ddorwin, 2012/08/16 04:15:48]

More accurately, we'll need to do some experimentation to make sure we can
correctly abstract PPB_Buffer_Dev, and I'd like to have the PPAPI, sample CDM,
and this landed so we can experiment on a stable base.

[scherkus (not reviewing), 2012/08/16 21:18:57]

For (3) I'm assuming we would build both halves of the plugin (PPAPI glue code +
the implementation of this interface) using the same checkout.

+  // parameters (e.g |session_id|) and passed the ownership to the caller.
+  // Returns kCdmStatusErrorUnknown otherwise, in which case the output
+  // parameters should not be used by the caller.
+  virtual CdmStatus GenerateKeyRequest(const uint8_t* init_data,
+                                       int init_data_size,
+                                       char** session_id,
+                                       int* session_id_size,
+                                       uint8_t** key_request,
+                                       int* key_request_size,
+                                       char** default_url,
+                                       int* default_url_size) = 0;
+
+  // Adds the |key| to the CDM.
+  // Returns kCdmStatusSuccess if the key is successfully added.
+  // Returns kCdmStatusErrorUnknown otherwise.
+  virtual CdmStatus AddKey(const char* session_id,
+                           int session_id_size,
+                           const uint8_t* key,
+                           int key_size) = 0;
+
+  // Cancels any pending key request made to the CDM for |session_id|.
+  // Returns kCdmStatusSuccess if all pending key requests for |session_id| are
+  // successfully canceled or there is no key request to be canceled.

[ddorwin, 2012/08/15 06:48:10]

FYI, TBD what to do if no matching session. May be moot after switching to OO
API.

+  // Returns kCdmStatusErrorUnknown otherwise.
+  virtual CdmStatus CancelKeyRequest(const char* session_id,
+                                     int session_id_size) = 0;
+
+  // Decrypts the |encrypted_buffer|.
+  // Returns kCdmStatusSuccess if decryption succeeds, in which case the callee
+  // should have filled the |decrypted_buffer| and passed the ownership of
+  // |data| in |decrypted_buffer| to the caller.
+  // Returns kCdmStatusErrorNoKey if the CDM does not have the necessary
+  // decryption key to decrypt.
+  // Returns kCdmStatusErrorUnknown if any other error happens.
+  // In these two cases, |decrypted_buffer| should not be used by the caller.
+  virtual CdmStatus Decrypt(const char* session_id,
+                            int session_id_size,
+                            const InputBuffer& encrypted_buffer,
+                            OutputBuffer* decrypted_buffer) = 0;
+
+  virtual ~ContentDecryptionModule() {};
+};
+
+#endif  // WEBKIT_MEDIA_CRYPTO_CONTENT_DECRYPTION_MODULE_H_