add key rotation method

update readme

Author: aminyazdanpanah

README.md

@@ -19,7 +19,7 @@ This package uses the **[FFmpeg](https://ffmpeg.org)** to package media content
   - [Opening a Resource](#opening-a-resource)
   - [DASH](#dash)
   - [HLS](#hls)
-    - [Encrypted HLS](#encrypted-hls)
+    - [DRM (Encrypted HLS)](#drm-encrypted-hls)
   - [Progress](#progress)
   - [Saving Files](#saving-files)
   - [Probe](#probe)
@@ -46,13 +46,13 @@ pip install python-ffmpeg-video-streaming
 ### Opening a Resource
 There are two ways to open a file:
 
-#### 1. From a FFmpeg supported resources
+#### 1. From a FFmpeg supported resource
 You can pass a local path of video(or a supported resource) to the method(`hls` or `dash`):
 ```python
 video = '/var/www/media/videos/video.mp4'
 ```
 
-For opening a file from a supported FFmpeg resource such as `http`, `ftp`, `pipe`, `rtmp` and etc. please see **[FFmpeg Protocols Documentation](https://ffmpeg.org/ffmpeg-protocols.html)**
+For opening a file from a supported resource such as `http`, `ftp`, `pipe`, `rtmp` and etc. please see **[FFmpeg Protocols Documentation](https://ffmpeg.org/ffmpeg-protocols.html)**
 
 **For example:** 
 ```python
@@ -142,11 +142,14 @@ r_720p = Representation(width=1280, height=720, kilo_bitrate=2048)
 ```
 **NOTE:** You cannot use HEVC(libx265) and VP9 formats for HLS packaging.
 
-#### Encrypted HLS
+#### DRM (Encrypted HLS)
 The encryption process requires some kind of secret (key) together with an encryption algorithm. HLS uses AES in cipher block chaining (CBC) mode. This means each block is encrypted using the ciphertext of the preceding block. [Learn more](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation)
 
 You must specify a path to save a random key to your local machine and also a URL(or a path) to access the key on your website(the key you will save must be accessible from your website). You must pass both these parameters to the `encryption` method:
 
+##### Single Key
+The following code generates a key for all TS files.
+
 ```python
 import ffmpeg_streaming
 
@@ -166,7 +169,46 @@ url = 'https://www.aminyazdanpanah.com/PATH_TO_KEY_DIRECTORY/random_key.key'
         .package('/var/www/media/videos/hls/hls-stream.m3u8')
 )
 ```
-**NOTE:** It is very important to protect your key on your website using a token or a session/cookie(****It is highly recommended****).    
+
+##### Key Rotation
+The code below, allows you to encrypt each TS file with a new encryption key. This can improve security and allows for more flexibility. You can also modify the code to use a different key for each set of segments(i.e. if 10 TS files has been generated then rotate the key) or you can generate a new encryption key at every periodic time(i.e. every 10 seconds).
+```python
+import tempfile
+from os.path import join
+from random import randrange
+
+import ffmpeg_streaming
+from ffmpeg_streaming.key_info_file import generate_key_info_file
+
+save_to = '/home/public_html/PATH_TO_KEY_DIRECTORY/key_rotation'
+url = 'https://www.aminyazdanpanah.com/PATH_TO_KEY_DIRECTORY/key_rotation'
+key_info_file_path = join(tempfile.gettempdir(), str(randrange(1000, 100000)) + '_py_ff_vi_st.tmp')
+k_num = 1
+
+
+def k_format(name, num):
+    return str(name) + "_" + str(num)
+
+
+def progress(per, ffmpeg):
+    global k_num
+    if ".ts' for writing" in ffmpeg:
+        # A new TS file has been created!
+        generate_key_info_file(k_format(url, k_num), k_format(save_to, k_num), key_info_path=key_info_file_path)
+        k_num += 1
+
+(
+    ffmpeg_streaming
+        .hls(video, hls_flags="periodic_rekey")
+        .encryption(url, save_to, key_info_path=key_info_file_path)
+        .format('libx264')
+        .auto_rep()
+        .package('/var/www/media/videos/hls/hls-stream.m3u8', progress=progress)
+)
+```
+**NOTE:** It is very important to protect your key(s) on your website using a token or a session/cookie(****It is highly recommended****).    
+
+**NOTE:** However HLS supports AES encryption, that you can encrypt your streams, it is not a full DRM solution. If you want to use a full DRM solution, I recommend to try **[FairPlay Streaming](https://developer.apple.com/streaming/fps/)** solution which then securely exchange keys, and protect playback on devices.
 
 See **[HLS examples](https://github.com/aminyazdanpanah/python-ffmpeg-video-streaming/tree/master/examples/hls)** and **[HLS options](https://ffmpeg.org/ffmpeg-formats.html#hls-2)** for more information.
 
@@ -276,7 +318,7 @@ A path can also be passed to save a copy of files to your local machine.
                  progress=progress)
 )
 ```
-**NOTE:** This option(Save To Clouds) is only for **[VOD](https://en.wikipedia.org/wiki/Video_on_demand)** (it does not support live streaming).
+**NOTE:** This option(Save To Clouds) is only valid for **[VOD](https://en.wikipedia.org/wiki/Video_on_demand)** (it does not support live streaming).
 
 **Schema:** The relation is `one-to-many`.
 

examples/hls/hls_encryption.py

@@ -62,7 +62,7 @@ def main():
     (
         ffmpeg_streaming
             .hls(args.input)
-            .encryption(args.key, args.url)
+            .encryption(args.url, args.key)
             .format('libx264')
             .auto_rep()
             .package(args.output, progress=transcode_progress)

examples/hls/hls_encryption_key_rotation.py

@@ -0,0 +1,67 @@
+"""
+examples.hls.hls_encryption
+~~~~~~~~~~~~
+
+Create encrypted HlS streams and manifests
+
+
+:copyright: (c) 2019 by Amin Yazdanpanah.
+:website: https://www.aminyazdanpanah.com
+:email: [email protected]
+:license: MIT, see LICENSE for more details.
+"""
+
+import argparse
+import sys
+import logging
+import tempfile
+from os.path import join
+from random import randrange
+
+import ffmpeg_streaming
+from ffmpeg_streaming.key_info_file import generate_key_info_file
+
+logging.basicConfig(filename='streaming.log', level=logging.NOTSET, format='[%(asctime)s] %(levelname)s: %(message)s')
+
+parser = argparse.ArgumentParser()
+parser.add_argument('-i', '--input', required=True, help='The path to the video file (required).')
+parser.add_argument('-key', '--key', required=True, help='The full pathname of the file where a random key will '
+                                                         'be created (required). Note: The path of the key should '
+                                                         'be accessible from your website(e.g. '
+                                                         '"/var/www/public_html/keys/enc.key")')
+parser.add_argument('-url', '--url', required=True, help='A URL (or a path) to access the key on your website ('
+                                                         'required). It is highly recommended to protect the key '
+                                                         'on your website(e.g using a token or check a '
+                                                         'session/cookie)')
+parser.add_argument('-o', '--output', default=None, help='The output to write files.')
+args = parser.parse_args()
+
+
+key_info_file_path = join(tempfile.gettempdir(), str(randrange(1000, 100000)) + '_py_ff_vi_st.tmp')
+k_num = 1
+
+
+def k_format(name, num):
+    return str(name) + "_" + str(num)
+
+
+def progress(per, ffmpeg):
+    global k_num
+    if ".ts' for writing" in ffmpeg:
+        generate_key_info_file(k_format(args.url, k_num), k_format(args.key, k_num), key_info_path=key_info_file_path)
+        k_num += 1
+
+
+def main():
+    (
+        ffmpeg_streaming
+            .hls(args.input, hls_flags="periodic_rekey")
+            .encryption(args.url, args.key, key_info_path=key_info_file_path)
+            .format('libx264')
+            .auto_rep()
+            .package(args.output, progress=progress)
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ffmpeg_streaming/__init__.py

@@ -2,6 +2,7 @@
 from .media import *
 from .rep import *
 from .clouds import *
+from .key_info_file import *
 
 VERSION = '0.0.13'
-__all__ = _ffprobe.__all__ + media.__all__ + rep.__all__ + clouds.__all__
+__all__ = _ffprobe.__all__ + media.__all__ + rep.__all__ + clouds.__all__ + key_info_file.__all__

ffmpeg_streaming/key_info_file.py

@@ -15,9 +15,20 @@
 from secrets import token_bytes, token_hex
 
 
-def generate_key_info_file(url, path, length=16):
+def generate_key_info_file(url, path, key_info_path=None, length=16):
     with open(path, 'wb') as key:
         key.write(token_bytes(length))
-    with tempfile.NamedTemporaryFile(mode='w', suffix='_py_ff_vi_st.tmp', delete=False) as key_info:
+
+    if key_info_path is None:
+        _key_info_file = tempfile.NamedTemporaryFile(mode='w', suffix='_py_ff_vi_st.tmp', delete=False)
+    else:
+        _key_info_file = open(key_info_path, mode="w")
+
+    with _key_info_file as key_info:
         key_info.write("\n".join([url, path, token_hex(length)]))
     return key_info.name
+
+
+__all__ = [
+    'generate_key_info_file',
+]

ffmpeg_streaming/media.py

@@ -55,7 +55,8 @@ def _save_hls_master_playlist(output, master_playlist_path, dirname, name):
 class Export(object):
     video_format = str
     audio_format = str
-    _ffprobe = dict
+    _ffprobe = None
+    _ffmpeg = None
     reps = list
     output = str
     _is_tmp_directory = False
@@ -113,14 +114,14 @@ def package(
             _save_hls_master_playlist(output, self.master_playlist_path, dirname, name)
 
         with Process(progress, build_command(cmd, self), c_stdout, c_stderr, c_stdin) as process:
-            p = process.run(c_input, timeout)
+            Export._ffmpeg = process.run(c_input, timeout)
 
         save_to_clouds(clouds, dirname)
 
         if output is not None and clouds is not None:
             shutil.move(dirname, os.path.dirname(output))
 
-        return self, p, Export._ffprobe
+        return self
 
 
 class HLS(Export):
@@ -133,8 +134,8 @@ def __init__(self, filename, **options):
         self.hls_key_info_file = options.pop('hls_key_info_file', None)
         super(HLS, self).__init__(filename, options)
 
-    def encryption(self, url, path, length=16):
-        self.hls_key_info_file = generate_key_info_file(url, path, length)
+    def encryption(self, url, path, key_info_path=None, length=16):
+        self.hls_key_info_file = generate_key_info_file(url, path, key_info_path, length)
         return self