Update DRM documentations

Fixes: #245. Fixes: #306. Change-Id: Ib847f5cfbf01b98f7a7e088dfcbc4d25cbbc15f2
shaka-project · Aug 16, 2018 · 451406a · 451406a
1 parent 9c08808
commit 451406a
Show file tree

Hide file tree

Showing 7 changed files with 110 additions and 55 deletions.
diff --git a/docs/source/options/hls_options.rst b/docs/source/options/hls_options.rst
@@ -13,8 +13,9 @@ HLS options
 
 --hls_key_uri <uri>
 
-    The key uri for 'identity' and 'com.apple.streamingkeydelivery' key formats.
-    Ignored if the playlist is not encrypted or not using the above key formats.
+    The key uri for 'identity' and 'com.apple.streamingkeydelivery' (FairPlay)
+    key formats. Ignored if the playlist is not encrypted or not using the above
+    key formats.
 
 --hls_playlist_type <type>
 

diff --git a/docs/source/options/playready_encryption_options.rst b/docs/source/options/playready_encryption_options.rst
@@ -18,16 +18,18 @@ PlayReady encryption options
 --ca_file <file path>
 
     Absolute path to the certificate authority file for the server cert.
-    PEM format.
+    PEM format. Optional, depends on server configuration.
 
 --client_cert_file <file path>
 
-    Absolute path to client certificate file.
+    Absolute path to client certificate file. Optional, depends on server
+    configuration.
 
 --client_cert_private_key_file <file path>
 
-    Absolute path to the private key file.
+    Absolute path to the private key file. Optional, depends on server
+    configuration.
 
 --client_cert_private_key_password <string>
 
-    Password to the private key file.
+    Password to the private key file. Optional, depends on server configuration.
diff --git a/docs/source/tutorials/drm.rst b/docs/source/tutorials/drm.rst
@@ -1,9 +1,22 @@
 DRM
 ===
 
+Shaka Packager supports fetching encryption keys from Widevine Key Server and
+PlayReady Key Server. In addition, Shaka Packager also supports Raw Keys, for
+which keys and key_ids are provided to Shaka Packager directly.
+
 .. toctree::
     :maxdepth: 2
 
     /tutorials/raw_key.rst
     /tutorials/widevine.rst
     /tutorials/playready.rst
+
+Regardless of which key server you are using, you can instruct Shaka Packager to
+generate other protection systems in additional to the native protection system
+from the key server. This allows generating multi-DRM contents easily.
+
+.. include:: /options/drm_stream_descriptors.rst
+.. include:: /options/general_encryption_options.rst
+.. include:: /options/widevine_encryption_options.rst
+.. include:: /options/raw_key_encryption_options.rst
diff --git a/docs/source/tutorials/playready.rst b/docs/source/tutorials/playready.rst
@@ -1,4 +1,29 @@
-PlayReady
-=========
+Using PlayReady Key Server
+==========================
 
-To be completed.
+Shaka Packager can talk to PlayReady Key Server that implements
+`AcquirePackagingData Web Method specification <http://bit.ly/2M9NuOt>`_ to
+fetch encryption keys.
+
+Refer to :doc:`/tutorials/drm` if you are interested in generating multi-DRM
+contents.
+
+Synopsis
+--------
+
+    $ packager <stream_descriptor> ... \
+      --enable_playready_encryption \
+      --playready_server_url <playready_server_url> \
+      --program_identifier <program_identifier> \
+      --client_cert_file <client_cert_file> \
+      --client_cert_private_key_file <client_cert_private_key_file> \
+      --client_cert_private_key_password <client_cert_private_key_password> \
+      --ca_file <ca_file> \
+      [Other options, e.g. DASH options, HLS options]
+
+The --client_cert_xx and --ca_file parameters can be omitted if not required by
+the key server.
+
+.. include:: /options/drm_stream_descriptors.rst
+.. include:: /options/general_encryption_options.rst
+.. include:: /options/playready_encryption_options.rst
diff --git a/docs/source/tutorials/raw_key.rst b/docs/source/tutorials/raw_key.rst
@@ -1,7 +1,11 @@
-Raw key
-=======
+Using Raw Key
+=============
 
-*Packager* allows encrypting contents with raw key.
+Shaka Packager supports raw keys, for which keys and key_ids are provided to
+Shaka Packager directly.
+
+This is often used if you are managing the encryption keys yourself. It also
+allows you to support multi-DRM by providing custom PSSHs.
 
 Synopsis
 --------
@@ -18,28 +22,30 @@ Synopsis
 
     label=<label>:key_id=<key_id>:key=<key>
 
-Custom PSSH(s) can be provided in *--pssh*. If absent,
-`v1 common PSSH box <https://goo.gl/s8RIhr>`_ is generated.
+Custom PSSH(s) can be provided in *--pssh*. If neither --pssh nor
+--protection_systems is specified, `v1 common PSSH box <https://goo.gl/s8RIhr>`_
+is generated.
 
 Examples
 --------
 
-The examples below use the H264 streams created in :doc:`encoding`. Here are
-examples with DASH. It can be applied to HLS in a similar way.
+The examples below use the H264 streams created in :doc:`encoding`.
 
-Common PSSH (one key for all streams)::
+* Example with pre-generated PSSH::
 
     $ packager \
-      in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4 \
-      in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4 \
-      in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \
-      in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \
-      in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \
+      in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
+      in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
+      in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
+      in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
+      in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
       --enable_raw_key_encryption \
-      --keys label=:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392 \
-      --mpd_output h264.mpd
+      --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
+      --pssh 000000317073736800000000EDEF8BA979D64ACEA3C827DCD51D21ED00000011220F7465737420636F6E74656E74206964 \
+      --mpd_output h264.mpd \
+      --hls_master_playlist_output h264_master.m3u8
 
-Common PSSH (different keys for different streams)::
+* Common PSSH is generated if no PSSH or protection system flag is specified::
 
     $ packager \
       in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
@@ -51,20 +57,23 @@ Common PSSH (different keys for different streams)::
       --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
       --mpd_output h264.mpd
 
-Widevine (with pre-generated Widevine PSSH)::
+* Example with FairPlay using 'cbcs' protection scheme::
 
     $ packager \
       in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
       in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,drm_label=SD \
       in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,drm_label=SD \
       in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,drm_label=HD \
       in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,drm_label=HD \
+      --protection_scheme cbcs \
       --enable_raw_key_encryption \
       --keys label=AUDIO:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519,label=SD:key_id=abba271e8bcf552bbd2e86a434a9a5d9:key=69eaa802a6763af979e8d1940fb88392,label=HD:key_id=6d76f25cb17f5e16b8eaef6bbf582d8e:key=cb541084c99731aef4fff74500c12ead \
-      --pssh 000000317073736800000000EDEF8BA979D64ACEA3C827DCD51D21ED00000011220F7465737420636F6E74656E74206964 \
-      --mpd_output h264.mpd
+      --protection_systems FairPlay \
+      --iv 11223344556677889900112233445566
+      --hls_master_playlist_output h264_master.m3u8 \
+      --hls_key_uri skd://testAssetID
 
-Widevine and PlayReady::
+* Example with multi-drm (Widevine and PlayReady)::
 
     $ packager \
       in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,drm_label=AUDIO \
@@ -79,8 +88,9 @@ Widevine and PlayReady::
 
 .. note::
 
-    User is responsible for setting up Widevine and PlayReady license server and
-    managing keys there.
+    Users are responsible for setting up the license servers and managing keys
+    there unless they are using a cloud service provided by the DRM provider or
+    third_parties.
 
 Refer to
 `player setup <https://shaka-player-demo.appspot.com/docs/api/tutorial-drm-config.html>`_

diff --git a/docs/source/tutorials/widevine.rst b/docs/source/tutorials/widevine.rst
@@ -1,18 +1,19 @@
-Widevine
-========
+Using Widevine Key Server
+=========================
 
-There are two options to package a Widevine DRM encrypted content:
+The easiest way to generate Widevine protected content is to use Widevine Cloud
+Service.
 
-1. If you know the encryption keys and have the associated Widevine PSSH at
-   hand, you can provide them in clear text to *packager* directly. Refer to
-   :doc:`/tutorials/raw_key` for details.
-
-2. Provide *key_server_url* and associated credentials to *packager*.
-   *Packager* will fetch encryption keys from Widevine key server.
+Shaka Packager can talk to Widevine Cloud Service or any key server that
+implements `Common Encryption API for Widevine DRM <http://bit.ly/2vTG4oo>`_ to
+fetch encryption keys.
 
 Synopsis
 --------
 
+Widevine Common Encryption API supports request validation using either AES or
+RSA.
+
 AES signing::
 
     $ packager <stream_descriptor> ... \
@@ -37,22 +38,22 @@ Examples
 
 The examples below use the H264 streams created in :doc:`encoding`.
 
-* Here is an example with both DASH and HLS output::
+* Example with both DASH and HLS output::
 
     $ packager \
       in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4 \
       in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4 \
       in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \
       in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \
       in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \
-      --mpd_output h264.mpd \
-      --hls_master_playlist_output h264_master.m3u8 \
       --enable_widevine_encryption \
       --key_server_url https://license.uat.widevine.com/cenc/getcontentkey/widevine_test \
       --content_id 7465737420636f6e74656e74206964 \
       --signer widevine_test \
       --aes_signing_key 1ae8ccd0e7985cc0b6203a55855a1034afc252980e970ca90e5202689f947ab9 \
-      --aes_signing_iv d58ce954203b7c9a9a9d467f59839249
+      --aes_signing_iv d58ce954203b7c9a9a9d467f59839249 \
+      --mpd_output h264.mpd \
+      --hls_master_playlist_output h264_master.m3u8
 
 * Another example using 'cbcs' protection scheme::
 
@@ -62,38 +63,41 @@ The examples below use the H264 streams created in :doc:`encoding`.
       in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \
       in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \
       in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \
-      --mpd_output h264.mpd \
-      --hls_master_playlist_output h264_master.m3u8 \
       --protection_scheme cbcs \
       --enable_widevine_encryption \
       --key_server_url https://license.uat.widevine.com/cenc/getcontentkey/widevine_test \
       --content_id 7465737420636f6e74656e74206964 \
       --signer widevine_test \
       --aes_signing_key 1ae8ccd0e7985cc0b6203a55855a1034afc252980e970ca90e5202689f947ab9 \
-      --aes_signing_iv d58ce954203b7c9a9a9d467f59839249
+      --aes_signing_iv d58ce954203b7c9a9a9d467f59839249 \
+      --mpd_output h264.mpd \
+      --hls_master_playlist_output h264_master.m3u8
 
-* One example with multi-DRM support (PlayReady in addition to Widevine)::
+The examples above generate Widevine protection system by default. It can be
+extended to support multi-drm with --protection_systems flag.
+
+* Example with multi-drm (Widevine and PlayReady)::
 
     $ packager \
       in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4 \
       in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4 \
       in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \
       in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \
       in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \
-      --mpd_output h264.mpd \
-      --hls_master_playlist_output h264_master.m3u8 \
       --enable_widevine_encryption \
       --key_server_url https://license.uat.widevine.com/cenc/getcontentkey/widevine_test \
       --content_id 7465737420636f6e74656e74206964 \
       --signer widevine_test \
       --aes_signing_key 1ae8ccd0e7985cc0b6203a55855a1034afc252980e970ca90e5202689f947ab9 \
       --aes_signing_iv d58ce954203b7c9a9a9d467f59839249 \
       --protection_systems Widevine,PlayReady
+      --mpd_output h264.mpd
 
 .. note::
 
-    User is responsible for setting up the PlayReady server and managing keys
-    there.
+    Users are responsible for setting up the license servers and managing keys
+    there unless they are using a cloud service provided by the DRM provider or
+    third_parties.
 
 Refer to
 `player setup <https://shaka-player-demo.appspot.com/docs/api/tutorial-drm-config.html>`_

diff --git a/packager/hls/base/simple_hls_notifier.cc b/packager/hls/base/simple_hls_notifier.cc
@@ -472,9 +472,9 @@ bool SimpleHlsNotifier::NotifyEncryptionUpdate(
     return true;
   }
 
-  LOG(ERROR) << "Unknown system ID: "
-             << base::HexEncode(system_id.data(), system_id.size());
-  return false;
+  LOG(WARNING) << "HLS: Ignore unknown or unsupported system ID: "
+               << base::HexEncode(system_id.data(), system_id.size());
+  return true;
 }
 
 bool SimpleHlsNotifier::Flush() {