mirror of
https://github.com/hyugogirubato/KeyDive.git
synced 2026-07-15 18:40:02 +02:00
92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
# 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 |