Feature Request: Support for Custom CDM API Providers (Beyond Decrypt Lab)

[didisumard1]

Is your feature request related to a problem? Please describe.
Currently, Unshackle only supports Decrypt Lab as the CDM API provider. I would like to be able to use my own custom CDM API endpoint for greater flexibility and control over the decryption process.

Describe the solution you'd like
Add support for custom CDM API providers with the following features:

• Configurable API endpoint URL in the configuration file
• Support for different authentication methods (API keys, tokens, secrets)
• Flexible API request/response format configuration
• Support for custom challenge and license paths
• Ability to specify device information (device_type, system_id, security_level)
• Support for legacy API formats

Example configuration format:

remote_cdm:

• name: "CHROME"
  device_name: "ChromeCDM"
  device_type: "CHROME"
  system_id: 34312
  security_level: 3
  host: "https://"
  secret: "your-secret-key"
  challenge_path: "/get-challenge"
  license_path: "/get-keys"
  legacy: true
  drm_type: "Widevine"
  path: "{data_dir}/key_store.db"

Describe alternatives you've considered
Currently, the only option is to use Decrypt Lab, which limits flexibility for users who have their own CDM infrastructure or prefer to use different CDM API providers.

Additional context
This feature would allow users like me to:

• Use self-hosted CDM API solutions
• Connect to custom CDM services with different endpoint structures
• Have better control over the decryption process
• Reduce dependency on a single external service
• Improve privacy and security by keeping decryption keys within their own infrastructure
• Use existing CDM APIs that follow similar patterns to the example above

Thank you for considering this feature request!

[Sp5rky]

You can already achieve what you're looking for with the current decrypt_labs type. The decrypt_labs type in unshackle is specifically designed to work with custom CDM API endpoints that follow the Decrypt Labs KeyXtractor API format.

The decrypt_labs type configuration already supports exactly what you're asking for. Here's how to configure it for your custom endpoint:

remote_cdm:
  - name: "my_custom_chrome"
    type: "decrypt_labs"          # Uses the DecryptLabsRemoteCDM implementation
    device_name: "ChromeCDM"      # Scheme identifier (ChromeCDM, L1, L2, SL2, SL3)
    device_type: CHROME           # Device type (CHROME, ANDROID, PLAYREADY)
    system_id: 34312              # System ID for compatibility
    security_level: 3             # Security level
    host: "https://your-custom-endpoint.com"  # Your custom API endpoint
    secret: "your-api-key"        # Your authentication key

For your custom CDM API to work with the decrypt_labs type, it needs to implement two endpoints that follow the Decrypt Labs KeyXtractor API format:

1. POST /get-request

Request:

{
  "scheme": "ChromeCDM",
  "init_data": "base64_encoded_pssh",
  "get_cached_keys_if_exists": true,
  "service": "optional_service_name",
  "service_certificate": "optional_base64_cert"
}

Response (for cached keys):

{
  "message": "success",
  "message_type": "cached-keys",
  "cached_keys": [
    {"kid": "key_id_hex", "key": "key_hex", "type": "CONTENT"}
  ]
}

Response (for license request):

{
  "message": "success",
  "message_type": "license-request",
  "challenge": "base64_encoded_challenge",
  "session_id": "session_identifier"
}

2. POST /decrypt-response

Request:

{
  "scheme": "ChromeCDM",
  "session_id": "session_from_get_request",
  "init_data": "base64_encoded_pssh",
  "license_request": "base64_challenge",
  "license_response": "base64_license"
}

Response:

{
  "message": "success",
  "keys": [
    {"kid": "key_id_hex", "key": "key_hex", "type": "CONTENT"}
  ]
}

While we could add a separate custom type, it would functionally be identical to decrypt_labs since they'd need to implement the same API contract. The decrypt_labs type name might be slightly misleading since it works with any API endpoint that follows the KeyXtractor format, not just the official Decrypt Labs service.

1. Ensure your custom CDM API implements the two endpoints above (/get-request and /decrypt-response) with the expected request/response formats
2. Configure it in your unshackle.yaml using the decrypt_labs type with your custom host URL

If your custom API uses a different request/response format, you would need to either:

• Modify your API to match the KeyXtractor format, or
• Create a translation layer/proxy that converts between your format and the KeyXtractor format

Let me know if you have any questions about implementing the API endpoints or if there's something specific about your use case that isn't covered!

[didisumard1]

You can already achieve what you're looking for with the current decrypt_labs type. The decrypt_labs type in unshackle is specifically designed to work with custom CDM API endpoints that follow the Decrypt Labs KeyXtractor API format.

The decrypt_labs type configuration already supports exactly what you're asking for. Here's how to configure it for your custom endpoint:

remote_cdm:
  - name: "my_custom_chrome"
    type: "decrypt_labs"          # Uses the DecryptLabsRemoteCDM implementation
    device_name: "ChromeCDM"      # Scheme identifier (ChromeCDM, L1, L2, SL2, SL3)
    device_type: CHROME           # Device type (CHROME, ANDROID, PLAYREADY)
    system_id: 34312              # System ID for compatibility
    security_level: 3             # Security level
    host: "https://your-custom-endpoint.com"  # Your custom API endpoint
    secret: "your-api-key"        # Your authentication key

For your custom CDM API to work with the decrypt_labs type, it needs to implement two endpoints that follow the Decrypt Labs KeyXtractor API format:

1. POST /get-request

Request:

{
  "scheme": "ChromeCDM",
  "init_data": "base64_encoded_pssh",
  "get_cached_keys_if_exists": true,
  "service": "optional_service_name",
  "service_certificate": "optional_base64_cert"
}

Response (for cached keys):

{
  "message": "success",
  "message_type": "cached-keys",
  "cached_keys": [
    {"kid": "key_id_hex", "key": "key_hex", "type": "CONTENT"}
  ]
}

Response (for license request):

{
  "message": "success",
  "message_type": "license-request",
  "challenge": "base64_encoded_challenge",
  "session_id": "session_identifier"
}

2. POST /decrypt-response

Request:

{
  "scheme": "ChromeCDM",
  "session_id": "session_from_get_request",
  "init_data": "base64_encoded_pssh",
  "license_request": "base64_challenge",
  "license_response": "base64_license"
}

Response:

{
  "message": "success",
  "keys": [
    {"kid": "key_id_hex", "key": "key_hex", "type": "CONTENT"}
  ]
}

While we could add a separate custom type, it would functionally be identical to decrypt_labs since they'd need to implement the same API contract. The decrypt_labs type name might be slightly misleading since it works with any API endpoint that follows the KeyXtractor format, not just the official Decrypt Labs service.

1. Ensure your custom CDM API implements the two endpoints above (/get-request and /decrypt-response) with the expected request/response formats
2. Configure it in your unshackle.yaml using the decrypt_labs type with your custom host URL

If your custom API uses a different request/response format, you would need to either:

• Modify your API to match the KeyXtractor format, or
• Create a translation layer/proxy that converts between your format and the KeyXtractor format

Let me know if you have any questions about implementing the API endpoints or if there's something specific about your use case that isn't covered!

Thank you for the detailed explanation! I've tested my CDM API endpoint (https://chrome.drmkeys.me) and here's what I found:

My CDM API Format

Host: https://chrome.drmkeys.me

Authentication

• Uses header-based authentication: x-api-key: <api_key>
• NOT in the request body like KeyXtractor format

Endpoint 1: POST /get-challenge

Request Format:
{
"device": "ChromeCDM",
"init_data": "base64_encoded_pssh",
"scheme": "Widevine"
}

Required Headers:
Content-Type: application/json
x-api-key: <your_api_key>

Successful Response:
{
"message": "success",
"message_type": "license-request",
"challenge": "CAESqQwKwAsIARKgCgrcAggCEhCv0Vduc...",
"session_id": "4adb91557a3b875b85f09e9b31b10b57_generic",
"scheme": "Widevine"
}

Supported Schemes:

• "Widevine" ✅
• "ChromeCDM" ✅
• "CHROME" ❌ (returns error: "scheme is not supported or invalid")
• "cenc" ❌ (returns error: "scheme is not supported or invalid")

Endpoint 2: POST /get-keys

Request Format:
{
"device": "ChromeCDM",
"scheme": "Widevine",
"session_id": "session_from_get_challenge",
"init_data": "base64_encoded_pssh",
"license_request": "base64_challenge",
"license_response": "base64_license"
}

Required Headers:
Content-Type: application/json
x-api-key: <your_api_key>

Expected Response (based on error message):
{
"message": "success",
"keys": [...]
}

Note: The endpoint validates session_id - it must be obtained from the /get-challenge response first.

Key Differences from KeyXtractor Format

Feature	My API (chrome.drmkeys.me)	KeyXtractor Format
Authentication	Header: x-api-key	Body: secret field
Endpoint 1	/get-challenge	/get-request
Endpoint 2	/get-keys	/decrypt-response
Device Parameter	device: "ChromeCDM"	scheme: "ChromeCDM"
Scheme Parameter	scheme: "Widevine"	Might be different
Response Field	message, message_type	message, message_type (similar)

Questions & Next Steps

Given these differences, what would be the best approach?

Option A: Could Unshackle's decrypt_labs type be extended to support:

1. Header-based authentication (configurable header name like x-api-key)?
2. Configurable endpoint paths (/get-challenge vs /get-request)?
3. Custom parameter mapping (device → scheme conversion)?

Option B: Should I create a translation proxy that:

• Receives KeyXtractor format from Unshackle
• Translates to my API's format
• Returns KeyXtractor format back to Unshackle

Option C: Modify my CDM API to support the KeyXtractor format endpoints

Which approach would you recommend? I'm happy to implement a translation proxy if that's the cleanest solution, or contribute to Unshackle if extending the decrypt_labs type makes sense.

[Sp5rky]

Quickest fix with less headache is to do Option C, mirror the endpoints to match decrypt_labs for now till I come up with a solution to allow custom endpoint URLs etc, if you host it yourself will be easy fix but if its 3rd party doubt it'll be changed and will have to wait for version 2.0.0+

[didisumard1]

Quickest fix with less headache is to do Option C, mirror the endpoints to match decrypt_labs for now till I come up with a solution to allow custom endpoint URLs etc, if you host it yourself will be easy fix but if its 3rd party doubt it'll be changed and will have to wait for version 2.0.0+

Thanks for the quick response!

Since chrome.drmkeys.me is a 3rd party API that I don't host myself, I can't modify the endpoints to match the decrypt_labs format (Option C).

Feature Request for v2.0.0+

When you work on v2.0.0, would it be possible to add configuration options like:

remote_cdm:

• name: "CHROME"
  type: "custom_api"
  host: "https://chrome.drmkeys.me"
  endpoints:
  get_request: "/get-challenge"
  decrypt_response: "/get-keys"
  auth:
  type: "header"
  header_name: "x-api-key"
  key: "YOUR_API_KEY"
  request_mapping:
  scheme_param: "device"
  add_params:
  scheme: "Widevine"
  response_mapping:
  challenge_field: "challenge"
  session_field: "session_id"
  keys_field: "keys"

This would allow Unshackle to work with various CDM API formats without needing translation proxies.

[Sp5rky]

I've pushed a new dynamic custom CDM you can test in the feature/add-rest-api branch, if you want to test before it goes live and let me know how it goes.

[vinefeeder]

Why not take this opportunity to do the right thing and remove any pre-made facility to connect to a pay service?

A custom API should suit all API. Anyone OCD enough that they 'must' have L1 access, so they choose to pay for it, can, at least. do a little work in setting up.

Just remove DecryptLabs. It shouldn't exist!

[Sp5rky]

Why not take this opportunity to do the right thing and remove any pre-made facility to connect to a pay service?

A custom API should suit all API. Anyone OCD enough that they 'must' have L1 access, so they choose to pay for it, can, at least. do a little work in setting up.

Just remove DecryptLabs. It shouldn't exist!

Thats the plan, if this custom CDM works as I expect will be stripped out eventually

[didisumard1]

I've pushed a new dynamic custom CDM you can test in the feature/add-rest-api branch, if you want to test before it goes live and let me know how it goes.

Hi @Sp5rky!

I just tested the dynamic custom CDM implementation and I'm happy to report that it works perfectly! 🎉

Test Configuration

I configured the custom Remote CDM with the following setup in unshackle.yaml:

remote_cdm:
  - name: "chrome"
    type: "custom_api"
    host: "https://[redacted-cdm-api-endpoint]"
    timeout: 30
    device:
      name: "ChromeCDM"
      type: "CHROME"
      system_id: 34312
      security_level: 3
    auth:
      type: "header"
      header_name: "x-api-key"
      key: "[redacted-api-key]"
      custom_headers:
        "User-Agent": "Unshackle/2.0.0"
    endpoints:
      get_request:
        path: "/get-challenge"
        method: "POST"
        timeout: 30
      decrypt_response:
        path: "/get-keys"
        method: "POST"
        timeout: 30
    request_mapping:
      get_request:
        param_names:
          scheme: "device"
          init_data: "init_data"
        static_params:
          scheme: "Widevine"
      decrypt_response:
        param_names:
          scheme: "device"
          license_request: "license_request"
          license_response: "license_response"
        static_params:
          scheme: "Widevine"
    response_mapping:
      get_request:
        fields:
          challenge: "challenge"
          session_id: "session_id"
          message: "message"
          message_type: "message_type"
        response_types:
          - condition: "message_type == 'license-request'"
            type: "license_request"
        success_conditions:
          - "message == 'success'"
      decrypt_response:
        fields:
          keys: "keys"
          message: "message"
        key_fields:
          kid: "kid"
          key: "key"
          type: "type"
        success_conditions:
          - "message == 'success'"
    caching:
      enabled: true
      use_vaults: true
      check_cached_first: true

key_vaults:
  - type: "SQLite"
    name: "Local"
    path: "key_store.db"

  - type: "HTTP"
    name: "my_vault"
    host: "https://[redacted-vault-endpoint]"
    username: "[redacted]"
    password: "[redacted]"
    api_mode: "query"

Test Results

Test 1: Remote CDM Only (vaults disabled)

uv run unshackle dl -q 480 -sl id -w s01e01 Netflix 81040344

✅ Result: Successfully obtained decryption keys from remote CDM API

• Key retrieved: [redacted-kid]:[redacted-key]
• Cached to: 0/0 vaults (vaults were disabled for this test)
• Download completed successfully

Test 2: Remote CDM + Vault Caching

uv run unshackle dl -q 480 -sl id -w s01e02 Netflix 81040344

✅ Result: Keys successfully cached and retrieved from vault

• Loaded 2/2 Vaults (SQLite + HTTP)
• Key retrieved from cached vault (my_vault HTTP vault)
• Download completed in ~29 seconds

Test 3: Content Downloaded

• Title: Squid Game (Netflix 81040344)
• Episodes: S01E01-E02
• Quality: 480p
• Subtitles: Indonesian
• Audio: DD+ Atmos (auto-selected best quality)

Observations

1. ✅ Authentication works perfectly - The header-based API key authentication is working as expected
2. ✅ Request/Response mapping is correct - The dynamic mapping configuration properly handles the custom API format
3. ✅ Vault integration works - Keys are properly cached when vaults are enabled
4. ✅ Endpoint configuration is flexible - Custom paths (/get-challenge, /get-keys) work perfectly
5. ✅ Error handling is robust - Failed requests are handled gracefully

Feedback

The dynamic custom CDM implementation is production-ready from my testing. The configuration is very flexible and allows full customization of:

• Endpoint paths and methods
• Request parameter mapping
• Response field mapping
• Authentication mechanisms (header/query/body)
• Success/error conditions
• Vault caching behavior

This is exactly what I needed! Thank you for implementing this feature. 🙏

The only minor suggestion would be to add some example configurations in the documentation for common Remote CDM providers (if not already planned), but the current implementation is already excellent

[Sp5rky]

Glad you got it working, I'll keep it in dev branch for now till I get some more testing done.

[didisumard1]

Glad you got it working, I'll keep it in dev branch for now till I get some more testing done.

Sounds good! Take your time with the additional testing. 👍

I'm happy to help test any updates or edge cases if needed. The current implementation in the dev branch is working great for my use case (Netflix with custom CDM API + vault caching).

Let me know if you need any specific testing scenarios or feedback during the development phase. Always glad to contribute