ce_cdm/README

README for Widevine CDM Partner Kit v2.2
Date: 12/16/2014

This document provides additional details on installation, system
setup, building, and testing components of the Widevine Content
Decryption Module supplied in the Widevine CDM Partner Kit.
This document supplements the information found in the "WV Modular DRM
Security Integration Guide for Common Encryption (CENC): EME/Embedded
Device Supplement v2.1", which is the EME-specific portion of the
dcoeument "WV Modular DRM Security Integration Guide for Common
Encryption (CENC)".

Kit Contents

The Widevine CDM Partner Kit is distributed as an XZipped tar file
(.tar.xz).  To unpack the kit into your current working directory:

  tar xf widevine-cdm_<kit-version>.tar.xz

  cd widevine-cdm_<kit-version>

The remaining instructions will refer to this directory as <cdm-kit-dir>.

The top level directories and files of the kit are as follows:
  cdm - the CDM interface declarations and definitions, and tests
  core - the CDM implementation, and tests
  linux - platform-specific files for the CDM implementation
  oemcrypto - OEMCrypto declarations, a mock implementation, and tests
  platforms - platform-specific build configs
  README - this file
  run_test.sh - builds and tests the CDM with mock OEMCrypto

System Setup

Some third-party software packages are required to build the CDM, OEMCrypto,
and various test modules. The actual versions that have been used and
verified are listed here, but earlier or later versions may also work. If
you already have a different version of a particular package installed
on your system, then you should try the build and unit tests to see if
there are any issues.

The current set of third-party packages includes:

    - gTest and gMock (version 1.6.0)
    - protobufs (Google Protocol Buffers) (version 2.5)
    - OpenSSL (libssl and libcrypto) (version 1.0.1g)
    - stringencoders (https://code.google.com/p/stringencoders)
    - python (version 2.7 or better)
    - GYP (python-based build tool) (https://code.google.com/p/gyp,
      svn revision 1846)

The following sections provide information about acquiring
and installing some of these packages.  This is not a complete list, but
it tries to cover the items that do not follow the typical methodologies.
Also, the instructions apply to and were tested on an up-to-date Ubuntu
system.  They may not work on your system exactly as shown.

GYP

  The kit uses GYP (Generate Your Projects) to create makefiles.

  The standard GYP source release is through a subversion (svn) checkout
  of trunk.  Most of this kit's development and testing was performed with
  GYP revision 1846.  The newest revision at the time of this document
  is 1884. You may already have GYP installed on your system, or you may
  try "apt-get install gyp" to install the version packaged for your
  system. If you choose to install the latest revision (option 1) or install
  revision 1846 (option 2), follow the instructions below.

  GYP requires Python. You should already have python 2.7 or better on your
  system.  There is also a python package called setuptools that GYP requires.
  If the GYP build fails, see the section below to install setuptools.

      python --version    # will return "Python 2.7.3" or something similar

      mkdir <gyp-kit-root>
      cd <gyp-kit-root>

      # checkout latest GYP (option 1)
      svn checkout http://gyp.googlecode.com/svn/trunk/ gyp-read-only

      # checkout GYP revision 1846 (option 2)
      svn checkout http://gyp.googlecode.com/svn/trunk/ gyp-read-only -r1846

      cd gyp-read-only/
      ./setup.py build    # this will fail if setuptools is not installed
      sudo ./setup.py install

Python setuptools

  Do this if the "setup.py build" fails.

      mkdir <setuptools-temp>
      cd <setuptools-temp>
      wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py \
           -O - | sudo python

  Return to the GYP installation.

Google Protocol Buffers (protobufs)

  The following instructions will install the protobuf compiler and libraries
  in /usr.  The default installation directory is /usr/local, which you may
  also use, but you should make sure that an older version is not installed
  in /usr.

      protoc --version             # test whether protobufs already on system
      which protoc                 # where is it installed?
      mkdir <protobuf-kit-root>
      cd <protobuf-kit-root>
      wget http://protobuf.googlecode.com/files/protobuf-2.5.0.tar.gz
      tar xzf protobuf-2.5.0.tar.gz
      cd protobuf-2.5.0/
      ./configure --prefix=/usr --exec-prefix=/usr
      make
      sudo make install
      protoc --version

  The final command should return:  libprotoc 2.5.0

Google C++ Mocking Framework (gmock and gtest)

  The following instructions will install the Google Mock and
  Google Test frameworks. The package can exist anywhere on
  the build system. The kit uses gmock-1.6.0.zip and can be
  downloaded from https://code.google.com/p/googlemock/downloads/list.

      mkdir <gmock_dir>
      cd <gmock_dir>
      wget https://googlemock.googlecode.com/files/gmock-1.6.0.zip
      unzip gmock-1.6.0.zip
      cd <cdm-kit-dir>
      mkdir third_party
      cd third_party
      ln -sf <gmock_dir>/gmock-1.6.0 gmock

  The kit build will use the symlink when building the unit tests.

StringEncoders 3.10.3 (stringencoders)

  The following instructions will install and configure the
  stringencoders package. After configuring and building the
  package, several files must be copied to the kit.
  The kit uses stringencoders-v3.10.3.tar.gz which can be downloaded from
  https://code.google.com/p/stringencoders/downloads/list.

      mkdir <stringencoders-dir>
      cd <stringencoders-dir>
      wget \
      https://stringencoders.googlecode.com/files/stringencoders-v3.10.3.tar.gz
      tar xzvf stringencoders-v3.10.3.tar.gz
      cd stringencoders-v3.10.3
      ./configure --with-b64wchars='-_=' CFLAGS=-Wno-unused-but-set-variable
      make
      mkdir -p <cdm-kit-dir>/third_party/stringencoders/src
      cp modp_b64w_data.h <cdm-kit-dir>/third_party/stringencoders/src
      cp src/modp_b64w.c \
         <cdm-kit-dir>/third_party/stringencoders/src/modp_b64w.cpp
      cp src/modp_b64w.h <cdm-kit-dir>/third_party/stringencoders/src

  Note that the file extension of the source is changed from .c to .cpp.

  The final step will be to edit
  <cdm-kit-dir>/third_party/stringencoders/src/modp_b64w.cpp
  and comment out the line '#include "config.h"'.

What's in the kit?

The kit contains two major components and a small suite of unit tests:
a Widevine CDM and a Mock OEMCrypto.  These components will enable you
to create an OEMCrypto library and a CDM module for your target devices.

The CDM relies on OEMCrypto for performing secure operations.  The Mock
OEMCrypto uses OpenSSL to perform all OEMCrypto functions.  This library
is *NOT* secure and it *CANNOT* be used in a production environment, but
it allows you to verify your CDM port before you have a working OEMCrypto
for your device, plus it provides a reference implementation to help you
implement and verify your OEMCrypto.

The CDM uses a "Host" interface to communicate with the upper layers of
the system and also to obtain certain services it needs, such as timers
and file I/O support. This kit contains a simple implementation of the
Host interface.  You will create a complete Host interface for each of
your target devices.

Building components

The easiest way to build is to navigate to the top level directory of
the installed kit and run the following script. This does a full build
of the linux target and runs wvcdm_shared_api_unittest:

    ./run_test.sh

The top-level build script is build.py.  It configures the build
environment, runs GYP to generate a series of make files. and starts the
top level make.  The build scripts are parameterized to build for multiple
targets. All the pieces are provided to build for x86-64 (linux).  You
can use the x86-64 build as a template for building for your embedded targets.
The "CDM Porting Guide" supplied with this kit discusses the steps involved.

Configuring for a new target device

The kit "out of the box" builds a CDM module and links it into a unit
test executable image that can be run on your linux system.  To build
the CDM for a different target device, you will have to install an appropriate
toolchain and SDK for your targets.  Then you will have to extend
the build scripts to utilize these resources. You will also have to modify
or add certain source modules to integrate the CDM into your target's
media and/or browser environment.  This process is documented in the
"CDM Porting Guide".

Tests

Read the sections related to testing in the "WV Modular DRM Security
Integration Guide for Common Encryption (CENC): EME/Embedded Device
Supplement v2.1"

Test directories can be found in many of the kit's directories. The GYP files
for building the test images are found in the test directory or one level
above the test directory.  The test-releated GYP targets will have "test" or
"unittest" in the name.

Here's a current list of GYP files and test-related targets:

   File - Targets                  Purpose
    cdm/cdm.gyp
        license_protocol           Create protobuf sources for license protocol
        device_files               Create protobuf sources for license storage
        wvcdm_sysdep               Build system-dependent layer of CDM
        wvcdm_shared               Build CDM shared library
    cdm/cdm_unittests.gyp
        wvcdm_shared_api_unittest  Build CDM unit tests
    third_party/gmock.gyp
        gmock                      Provides gmock modules for unit tests
        gmock_main                 Provides main routine for unit tests
        gtest                      Provides gtest modules for unit tests
    oemcrypto/oemcrypto.gyp
        oec_lib                    Build OEMCrypto library
        oec_unittest               Build OEMCrypto unit tests
    oemcrypto/mock/oec_mock.gyp
        oec_mock                   Build mock OEMCrypto sources
    oemcrypto/prebuilt/oec_prebuilt.gyp
        oec_prebuilt               Integrate prebuilt OEMCrypto library

The "CDM Porting Guide" discusses how these targets are used and how you
will modify them to build libraries and test binaries for your target devices.

The "CDM Porting Guide", the "WV Modular DRM Security Integration Guide for
Common Encryption (CENC): EME/Embedded Device Supplement v2.1", and the
"WV Modular DRM Security Integration Guide for Common Encryption (CENC)"
should provide the information you need to create your OEMCrypto and CDM
implementations for your target devices.