# KeyDive: Widevine L3 Extractor for Android
KeyDive is a sophisticated Python script designed for precise extraction of Widevine L3 DRM (Digital Rights Management) keys from Android devices. This tool leverages the capabilities of the Widevine CDM (Content Decryption Module) to facilitate the recovery of DRM keys, enabling a deeper understanding and analysis of the Widevine L3 DRM implementation across various Android SDK versions.
> [!IMPORTANT]
> Support for OEM API 18+ (SDK > 33) requires the use of functions extracted from Ghidra.
## Features
- 🚀 Seamless Installation via [pip](#installation)
- 🔄 Automated extraction of Widevine L3 DRM keys
- 📱 Compatibility with a wide range of Android versions (SDK > 21), ensuring broad applicability
- 💾 Seamless extraction process, yielding essential DRM components
- 🌐 Offline extraction mode for environments without internet access
- 🖥️ Command-line options for flexible usage
- 🛠️ Support for custom functions extracted from Widevine libraries using Ghidra
- ❤️ Fully Open-Source! Pull Requests Welcome
## Prerequisites
Before you begin, ensure you have the following prerequisites in place:
1. **ADB (Android Debug Bridge):** Make sure to install [ADB](https://github.com/hyugogirubato/KeyDive/blob/main/docs/PACKAGE.md#adb-android-debug-bridge) and include it in your system's PATH environment variable for easy command-line access.
2. **Frida-Server:** Install `frida-server` on your target Android device. This requires root access on the device. For installation instructions and downloads, visit the [official Frida documentation](https://frida.re/docs/installation/).
## Installation
Follow these steps to set up KeyDive:
1. Ensure all prerequisites are met (see above).
2. Install KeyDive from PyPI using Poetry:
```shell
pip install keydive
```
## Usage
1. Play a DRM-protected video on the target device.
2. Launch the KeyDive script.
3. Reload the DRM-protected video on your device.
4. The script will automatically extract the Widevine L3 keys, saving them as follows:
- `client_id.bin` - This file contains device identification information.
- `private_key.pem` - This file contains the RSA private key for decryption.
This sequence ensures that the DRM-protected content is active and ready for key extraction by the time the KeyDive script is initiated, optimizing the extraction process.
### Command-Line Options
```shell
usage: keydive [-h] [-d <id>] [-v] [-l <dir>] [--delay <delay>] [--version] [-o <dir>] [-w] [-s] [-a] [-p] [-f <file>] [-k] [--challenge <file>] [--private-key <file>]
Extract Widevine L3 keys from an Android device.
options:
-h, --help show this help message and exit
Global:
-d <id>, --device <id>
Specify the target Android device ID for ADB connection.
-v, --verbose Enable verbose logging for detailed debug output.
-l <dir>, --log <dir>
Directory to store log files.
--delay <delay> Delay (in seconds) between process checks.
--version Display KeyDive version information.
Cdm:
-o <dir>, --output <dir>
Output directory for extracted data.
-w, --wvd Generate a pywidevine WVD device file.
-s, --skip Skip auto-detection of the private function.
-a, --auto Automatically start the Bitmovin web player.
-p, --player Install and start the Kaltura app automatically.
Advanced:
-f <file>, --functions <file>
Path to Ghidra XML functions file.
-k, --keybox Enable export of the Keybox data if it is available.
--challenge <file> Path to unencrypted challenge for extracting client ID.
--private-key <file> Path to private key for extracting client ID.
```
## Advanced Usage
### Extracting Functions
For advanced users looking to use custom functions with KeyDive, a comprehensive guide on extracting functions from Widevine libraries using Ghidra is available. Please refer to our [Functions Extraction Guide](https://github.com/hyugogirubato/KeyDive/blob/main/docs/FUNCTIONS.md) for detailed instructions.
### Offline Extraction
KeyDive supports offline extraction mode for situations without internet access. This mode allows you to extract DRM keys directly from your Android device. Ensure all necessary dependencies are installed and follow the detailed [Offline Mode Guide](https://github.com/hyugogirubato/KeyDive/blob/main/docs/OFFLINE.md) for step-by-step instructions.
### Obtaining Unencrypted Challenge Data
> [!NOTE]
> Usage of unencrypted challenge is not required by default. It is only necessary when the script cannot extract the client id.
To extract the unencrypted challenge data required for KeyDive's advanced features, follow the steps outlined in our [Challenge Extraction Guide](https://github.com/hyugogirubato/KeyDive/blob/main/docs/CHALLENGE.md). This data is crucial for analyzing DRM-protected content and enhancing your DRM key extraction capabilities.
### Temporary Disabling L1 for L3 Extraction
> [!WARNING]
> Usage of the module is now deprecated because the deactivation of the library was natively added.
Some manufacturers (e.g., Xiaomi) allow the use of L1 keyboxes even after unlocking the bootloader. In such cases, it's necessary to install a Magisk module called [liboemcrypto-disabler](https://github.com/hyugogirubato/KeyDive/blob/main/docs/PACKAGE.md#liboemcrypto-disabler) to temporarily disable L1, thereby facilitating L3 key extraction.
## Disclaimer
KeyDive is intended for educational and research purposes only. The use of this tool in unauthorized testing of protected content is strictly prohibited. Please ensure you have permission before proceeding with DRM key extraction.
## Contributors
<a href="https://github.com/hyugogirubato"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/65763543?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="hyugogirubato"/></a>
<a href="https://github.com/FoxRefire"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/155989196?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="FoxRefire"/></a>
<a href="https://github.com/azimabid00"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/110490898?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="azimabid00"/></a>
<a href="https://github.com/JohnDoe1964"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/167800584?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="JohnDoe1964"/></a>
<a href="https://github.com/Nineteen93"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/107993263?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="Nineteen93"/></a>
<a href="https://github.com/sn-o-w"><img src="https://images.weserv.nl/?url=avatars.githubusercontent.com/u/2406819?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d" alt="sn-o-w"/></a>
## Licensing
This software is licensed under the terms of [MIT License](https://github.com/hyugogirubato/KeyDive/blob/main/LICENSE).
You can find a copy of the license in the LICENSE file in the root folder.
* * *
© hyugogirubato 2024
Raw data
{
"_id": null,
"home_page": "https://github.com/hyugogirubato/KeyDive",
"name": "keydive",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "python, drm, widevine, google",
"author": "hyugogirubato",
"author_email": "65763543+hyugogirubato@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/74/be/02fb63ed7c37976d7f348534cb0aea1e0d5ed1ccc8bdc15ea3c570644f92/keydive-2.1.3.tar.gz",
"platform": null,
"description": "# KeyDive: Widevine L3 Extractor for Android\n\nKeyDive is a sophisticated Python script designed for precise extraction of Widevine L3 DRM (Digital Rights Management) keys from Android devices. This tool leverages the capabilities of the Widevine CDM (Content Decryption Module) to facilitate the recovery of DRM keys, enabling a deeper understanding and analysis of the Widevine L3 DRM implementation across various Android SDK versions.\n\n> [!IMPORTANT] \n> Support for OEM API 18+ (SDK > 33) requires the use of functions extracted from Ghidra.\n\n## Features\n\n- \ud83d\ude80 Seamless Installation via [pip](#installation)\n- \ud83d\udd04 Automated extraction of Widevine L3 DRM keys\n- \ud83d\udcf1 Compatibility with a wide range of Android versions (SDK > 21), ensuring broad applicability\n- \ud83d\udcbe Seamless extraction process, yielding essential DRM components\n- \ud83c\udf10 Offline extraction mode for environments without internet access\n- \ud83d\udda5\ufe0f Command-line options for flexible usage\n- \ud83d\udee0\ufe0f Support for custom functions extracted from Widevine libraries using Ghidra\n- \u2764\ufe0f Fully Open-Source! Pull Requests Welcome\n\n## Prerequisites\n\nBefore you begin, ensure you have the following prerequisites in place:\n\n1. **ADB (Android Debug Bridge):** Make sure to install [ADB](https://github.com/hyugogirubato/KeyDive/blob/main/docs/PACKAGE.md#adb-android-debug-bridge) and include it in your system's PATH environment variable for easy command-line access.\n2. **Frida-Server:** Install `frida-server` on your target Android device. This requires root access on the device. For installation instructions and downloads, visit the [official Frida documentation](https://frida.re/docs/installation/).\n\n## Installation\n\nFollow these steps to set up KeyDive:\n\n1. Ensure all prerequisites are met (see above).\n2. Install KeyDive from PyPI using Poetry:\n ```shell\n pip install keydive\n ```\n\n## Usage\n\n1. Play a DRM-protected video on the target device.\n2. Launch the KeyDive script.\n3. Reload the DRM-protected video on your device.\n4. The script will automatically extract the Widevine L3 keys, saving them as follows:\n - `client_id.bin` - This file contains device identification information.\n - `private_key.pem` - This file contains the RSA private key for decryption.\n\nThis sequence ensures that the DRM-protected content is active and ready for key extraction by the time the KeyDive script is initiated, optimizing the extraction process.\n\n### Command-Line Options\n\n```shell\nusage: keydive [-h] [-d <id>] [-v] [-l <dir>] [--delay <delay>] [--version] [-o <dir>] [-w] [-s] [-a] [-p] [-f <file>] [-k] [--challenge <file>] [--private-key <file>]\n\nExtract Widevine L3 keys from an Android device.\n\noptions:\n -h, --help show this help message and exit\n\nGlobal:\n -d <id>, --device <id>\n Specify the target Android device ID for ADB connection.\n -v, --verbose Enable verbose logging for detailed debug output.\n -l <dir>, --log <dir>\n Directory to store log files.\n --delay <delay> Delay (in seconds) between process checks.\n --version Display KeyDive version information.\n\nCdm:\n -o <dir>, --output <dir>\n Output directory for extracted data.\n -w, --wvd Generate a pywidevine WVD device file.\n -s, --skip Skip auto-detection of the private function.\n -a, --auto Automatically start the Bitmovin web player.\n -p, --player Install and start the Kaltura app automatically.\n\nAdvanced:\n -f <file>, --functions <file>\n Path to Ghidra XML functions file.\n -k, --keybox Enable export of the Keybox data if it is available.\n --challenge <file> Path to unencrypted challenge for extracting client ID.\n --private-key <file> Path to private key for extracting client ID.\n\n```\n\n## Advanced Usage\n\n### Extracting Functions\n\nFor advanced users looking to use custom functions with KeyDive, a comprehensive guide on extracting functions from Widevine libraries using Ghidra is available. Please refer to our [Functions Extraction Guide](https://github.com/hyugogirubato/KeyDive/blob/main/docs/FUNCTIONS.md) for detailed instructions.\n\n### Offline Extraction\n\nKeyDive supports offline extraction mode for situations without internet access. This mode allows you to extract DRM keys directly from your Android device. Ensure all necessary dependencies are installed and follow the detailed [Offline Mode Guide](https://github.com/hyugogirubato/KeyDive/blob/main/docs/OFFLINE.md) for step-by-step instructions.\n\n### Obtaining Unencrypted Challenge Data\n\n> [!NOTE] \n> Usage of unencrypted challenge is not required by default. It is only necessary when the script cannot extract the client id.\n\nTo extract the unencrypted challenge data required for KeyDive's advanced features, follow the steps outlined in our [Challenge Extraction Guide](https://github.com/hyugogirubato/KeyDive/blob/main/docs/CHALLENGE.md). This data is crucial for analyzing DRM-protected content and enhancing your DRM key extraction capabilities.\n\n### Temporary Disabling L1 for L3 Extraction\n\n> [!WARNING] \n> Usage of the module is now deprecated because the deactivation of the library was natively added.\n\nSome manufacturers (e.g., Xiaomi) allow the use of L1 keyboxes even after unlocking the bootloader. In such cases, it's necessary to install a Magisk module called [liboemcrypto-disabler](https://github.com/hyugogirubato/KeyDive/blob/main/docs/PACKAGE.md#liboemcrypto-disabler) to temporarily disable L1, thereby facilitating L3 key extraction.\n\n## Disclaimer\n\nKeyDive is intended for educational and research purposes only. The use of this tool in unauthorized testing of protected content is strictly prohibited. Please ensure you have permission before proceeding with DRM key extraction.\n\n## Contributors\n\n<a href=\"https://github.com/hyugogirubato\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/65763543?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"hyugogirubato\"/></a>\n<a href=\"https://github.com/FoxRefire\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/155989196?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"FoxRefire\"/></a>\n<a href=\"https://github.com/azimabid00\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/110490898?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"azimabid00\"/></a>\n<a href=\"https://github.com/JohnDoe1964\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/167800584?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"JohnDoe1964\"/></a>\n<a href=\"https://github.com/Nineteen93\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/107993263?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"Nineteen93\"/></a>\n<a href=\"https://github.com/sn-o-w\"><img src=\"https://images.weserv.nl/?url=avatars.githubusercontent.com/u/2406819?v=4&h=25&w=25&fit=cover&mask=circle&maxage=7d\" alt=\"sn-o-w\"/></a>\n\n\n## Licensing\n\nThis software is licensed under the terms of [MIT License](https://github.com/hyugogirubato/KeyDive/blob/main/LICENSE). \nYou can find a copy of the license in the LICENSE file in the root folder.\n\n* * * \n\n\u00a9 hyugogirubato 2024",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extract Widevine L3 keys from Android devices effortlessly, spanning multiple Android versions for DRM research and education.",
"version": "2.1.3",
"project_urls": {
"Changelog": "https://github.com/hyugogirubato/KeyDive/blob/main/CHANGELOG.md",
"Functions": "https://github.com/hyugogirubato/KeyDive/blob/main/docs/FUNCTIONS.md",
"Homepage": "https://github.com/hyugogirubato/KeyDive",
"Issues": "https://github.com/hyugogirubato/KeyDive/issues",
"Packages": "https://github.com/hyugogirubato/KeyDive/blob/main/docs/PACKAGE.md",
"Repository": "https://github.com/hyugogirubato/KeyDive"
},
"split_keywords": [
"python",
" drm",
" widevine",
" google"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c7c8a8714500179ab42d7c72c4d9c61dc7678b5c00b6229dccad7c7dbeca791",
"md5": "5588643438b191701c56ef89093ce42e",
"sha256": "820d8e4e2a97f4685e1b4aceafefcb318b5b642cc807488caf80f17d081f6882"
},
"downloads": -1,
"filename": "keydive-2.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5588643438b191701c56ef89093ce42e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 26630,
"upload_time": "2024-11-03T13:04:12",
"upload_time_iso_8601": "2024-11-03T13:04:12.610061Z",
"url": "https://files.pythonhosted.org/packages/3c/7c/8a8714500179ab42d7c72c4d9c61dc7678b5c00b6229dccad7c7dbeca791/keydive-2.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "74be02fb63ed7c37976d7f348534cb0aea1e0d5ed1ccc8bdc15ea3c570644f92",
"md5": "5658390ee2ced353276915bd246d2dfb",
"sha256": "41d820f98593b46ed0ca7fc931c8dd3c652e40f8246dc0f99e042b10b9969c64"
},
"downloads": -1,
"filename": "keydive-2.1.3.tar.gz",
"has_sig": false,
"md5_digest": "5658390ee2ced353276915bd246d2dfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 26722,
"upload_time": "2024-11-03T13:04:14",
"upload_time_iso_8601": "2024-11-03T13:04:14.299629Z",
"url": "https://files.pythonhosted.org/packages/74/be/02fb63ed7c37976d7f348534cb0aea1e0d5ed1ccc8bdc15ea3c570644f92/keydive-2.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-03 13:04:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hyugogirubato",
"github_project": "KeyDive",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "keydive"
}
JSON
