thegame_1980/KeyDive
1
0
Fork 0
mirror of https://github.com/hyugogirubato/KeyDive.git synced 2026-07-15 18:40:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

release v3.0.0

Browse Source
This commit is contained in:
hyugogirubato
2025-06-09 18:12:49 +02:00
parent 2f74b4c5b7
commit 82d6a903dd
28 changed files with 5384 additions and 1620 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEVELOPERS.md
+92
View File
@@ -0,0 +1,92 @@
# KeyDive Developer Documentation
This document explains the internal workings of KeyDive, including key concepts in the JS hook scripts, the meaning of critical fields, and the flow of the extraction process.
## Key Concepts & Terminology
| Key | Description |
|-----------------------|-------------------------------------------------------------------------------------------|
| `provisioning_method` | Indicates the method used to provision Widevine DRM. |
| `challenge` | Unencrypted challenge data sent to Widevine CDM to trigger provisioning or key requests. |
| `client_id` | Unique identifier extracted from the device representing the Widevine client credentials. |
| `private_key` | RSA private key used for DRM content decryption and authentication. |
| `keybox` | Device-specific key storage blob containing keys for DRM operations. |
| `certificate` | Device OEM certificate chain for verifying keys and trust. |
## Script Execution Flow
The core extraction logic is implemented in a Frida hook script injected into Widevine CDM processes. The following sequence diagram illustrates the general flow, including options for player choice and output formats:
````
+----------------+ +------------------+ +---------------------+ +------------------+
| Start Script | | Select Player | | Provisioning Method | | Extraction Steps |
+----------------+ +------------------+ +---------------------+ +------------------+
| | | |
|--(option: -a player)-->| Launch Kaltura app | |
| | | |
|--(option: -a web)----->| Launch Bitmovin player | |
| | | |
| | |---Check provisioning_method-->|
| | | |
| | |<--Send challenge data---------|
| | | |
| | |---Extract client_id---------->|
| | |---Extract private_key-------->|
| | |---Extract keybox (optional)-->|
| | | |
| | |---Export data to output dir-->|
| | | |
| | | |
V V V V
(Process ends) (Process ends) (Process ends) (Process ends)
````
## Key Data Handling
### Provisioning Method
The provisioning method determines how the device is authenticated with Widevine. Internally, KeyDive uses the following enum:
| Enum Value | Meaning |
|---------------------|-----------------------------------------------------------------------------|
| `ProvisioningError` | Device cannot be provisioned (typically unsupported or failed setup). |
| `DrmCertificate` | The device uses a pre-installed baked-in DRM certificate (usually L3 only). |
| `Keybox` | A factory-installed keybox is used to identify the device and decrypt keys. |
| `OEMCertificate` | A factory-provisioned OEM certificate chain is present for full L1 support. |
These values are automatically detected at runtime to determine the correct extraction strategy.
### Challenge Handling
The `challenge` is a critical blob of data sent during provisioning or license acquisition. KeyDive can:
- Intercept it during DRM playback.
- Accept an external file via the `--challenge` argument.
This challenge contains the encrypted request for keys or certificates and is essential for key extraction workflows.
### Client ID & Private Key
Both the `client_id` and `private_key` are extracted from the intercepted CDM functions. They are:
- Required for device emulation or license response reconstruction.
- Automatically exported to formats like `client_id.bin`, `private_key.pem`, and `.wvd`.
## Advanced Options & Debugging
The advanced command-line options allow:
- Overriding automatic provisioning detection.
- Injecting Ghidra-extracted symbol maps via `--symbols`.
- Forcing use of unencrypted challenges (`--unencrypt`) for debugging or fallback workflows.
- Extracting optional blobs like the Widevine keybox or certificates.
These are primarily useful for development, debugging, or supporting less common device models.
## Contribution Guidelines
Feel free to contribute by submitting PRs or reporting issues. Please follow the coding style and provide tests for new features.
---
© hyugogirubato 2025