PlayReady OCDM

The PlayReady OCDM (Open Content Decryption Module) component implements the Microsoft PlayReady DRM backend for WPEFramework (Thunder). It enables protected media playback by performing license acquisition, key binding, and hardware-accelerated content decryption through a standardized CDMi interface.

The component manages the complete lifecycle of a DRM session: parsing PlayReady PSSH initialization data extracted from the content manifest, generating a license challenge for dispatch to a license server, processing the license response to bind decryption keys, and decrypting encrypted media samples. The component is delivered as a shared object (Playready.drm) installed into the WPEFramework OCDM discovery directory and loaded by the WPEFramework OCDM Plugin (OpenCDMi) at runtime.

From a stack perspective, the component resides within WPEFramework (Thunder) and exposes the CDMi IMediaKeys and IMediaKeysExt interfaces to the WPEFramework OCDM Plugin (OpenCDMi) above it. Below, it depends on the PlayReady SDK for all DRM operations and on a platform-specific Secure Video Path (SVP) library (gst-svp-ext) for routing decrypted video content through protected memory without exposing it to normally accessible memory.

At the device level, the component allows PlayReady-protected video-on-demand and live streaming content to be played back on the device. At the module level, it manages the DRM application context lifecycle, session-scoped key state machines, license store maintenance, Secure Stop session tracking, and output protection policy enforcement.

flowchart LR

%% Apps Layer
    subgraph Apps["Apps & Runtimes"]
        FireboltApps["Firebolt Apps"]
        WPERuntime["WPE Runtime"]
    end

%% Middleware
    subgraph RDKMW["RDK Core Middleware"]
        OCDM["WPEFramework OCDM\n(OpenCDMi Plugin)"]
        PR["PlayReady OCDM\n(OpenCDMi Backend)"]
        Thunder["WPEFramework (Thunder)"]
    end

%% Vendor Layer
    subgraph VL["Vendor Layer"]
        PlayReadySDK["PlayReady SDK\n(SoC DRM Libraries)"]
        SvpGeneric["gst-svp-ext\n(Generic Interface)"]
        SvpHAL["gst-svp-ext\n(Platform HAL)"]
        SvpGeneric --> SvpHAL
    end

    subgraph Cloud["Cloud Services"]
        LicenseServer["License Server"]
    end

    Apps -->|"EME / OCDM API"| Thunder
    Thunder --> OCDM
    OCDM -->|"CDMi IMediaKeys"| PR
    PR -->|"Drm_* APIs\n(SoC DRM libs)"| PlayReadySDK
    PR -->|"svp_* APIs"| SvpGeneric
    PR -.->|"License Challenge / Response"| LicenseServer

Key Features & Responsibilities:

• License Acquisition: Generates a PlayReady license challenge from the DRM header present in the content and delivers it to the caller for dispatch to the license server. Processes the license server response and binds the resulting keys to per-key decrypt contexts.
• Content Decryption: Decrypts AES-CTR, AES-CBC, and AES-CBCS encrypted media samples using PlayReady opaque decrypt APIs, with subsample mapping support for mixed clear-and-encrypted content.
• Secure Video Path Integration: Routes decrypted video samples through protected memory regions using the SVP HAL, preventing video content from passing through normally accessible memory after decryption.
• Secure Stop: Tracks active playback sessions using the PlayReady Secure Stop mechanism and provides challenge generation and response processing APIs to allow a server to verify that playback has ended.
• Output Protection Enforcement: Evaluates license-specified output protection levels for compressed and uncompressed digital video, analog video, and digital audio outputs through a policy callback, and enforces maximum resolution decode constraints received from the license server.
• License Store Management: Maintains a persistent DRM store, performs cleanup of expired and removal-date licenses on initialization, supports store deletion, and provides a SHA-256 hash of the store for integrity verification.

Design

The component is structured around two layers: a system-level context managed by the PlayReady class in MediaSystem.cpp, and a per-session context managed by MediaKeySession in MediaSession.cpp and MediaSessionExt.cpp. The system layer initializes the PlayReady platform and maintains the shared DRM_APP_CONTEXT that sessions within the same instance share. The session layer manages individual key state machines, license challenge-response cycles, and decrypt context binding. This separation allows multiple concurrent sessions — such as those needed for multi-period content or adaptive bitrate streams with multiple key IDs — to share a single application context while maintaining independent key states.

PlayReady SDK calls that use the shared DRM_APP_CONTEXT are serialized through a global CriticalSection (drmAppContextMutex_) to ensure thread safety. Platform initialization is guarded separately by prPlatformMutex_ using a reference counter so that concurrent callers do not double-initialize. Session construction is protected by prSessionMutex_.

The component's northbound interface is the CDMi IMediaKeys and IMediaKeysExt API consumed by the WPEFramework OCDM Plugin (OpenCDMi) — the Thunder plugin responsible for discovering and loading OpenCDMi backend shared libraries and routing EME-layer requests to them. Its southbound interface covers two paths: PlayReady SDK calls for all DRM operations (directed to SoC-provided DRM libraries), and gst-svp-ext calls for SVP secure memory management — gst-svp-ext provides a generic interface where GStreamer SVP-specific platform handling is passed through to the underlying platform HAL. Configuration is delivered as a JSON string at Initialize() time, from which the DRM data directory, store path, and HOME environment variable are extracted.

The DRM store is persisted on the filesystem at the path specified by the store-location configuration parameter and is managed by the PlayReady SDK. The component performs a cleanup pass at startup to remove expired licenses. In-memory licenses are removed when the session closes. Temporary persistent licenses acquired during a session are tracked and deleted on session close to prevent unbounded accumulation.

graph LR

    OCDM["WPEFramework\nOCDM Plugin (OpenCDMi)"]

    subgraph Component["PlayReady OCDM (Playready.drm)"]
        subgraph SysL["System Layer"]
            SysCtx["DRM_APP_CONTEXT"]
            SecStop["Secure Stop"]
            StoreOps["Store Ops"]
        end
        Mutex["drmAppContextMutex_"]
        subgraph SessL["Session Layer"]
            KeySM["Key State Machine"]
            LicAcq["License Acq"]
            DecCtx["Decrypt Contexts"]
        end
    end

    PlayReadySDK["PlayReady SDK\n(SoC DRM Libraries)"]
    SvpGeneric["gst-svp-ext\n(Generic Interface)"]
    SvpHAL["gst-svp-ext\n(Platform HAL)"]
    SvpGeneric --> SvpHAL

    OCDM -->|"System APIs"| SysL
    OCDM -->|"Session APIs"| SessL
    SysL --> Mutex
    SessL --> Mutex
    Mutex --> PlayReadySDK
    SessL -->|"svp_* calls"| SvpGeneric

Threading Model

• Threading Architecture: Multi-threaded
• Main Thread: Handles IMediaKeys calls from the WPEFramework OCDM Plugin (OpenCDMi) — initialization, session creation, Secure Stop operations, and configuration.
• Worker Threads:
• Decrypt caller thread: Invokes Decrypt() on MediaKeySession; acquires drmAppContextMutex_ for the duration of each decrypt operation.
• Synchronization:
• drmAppContextMutex_ — global CriticalSection serializing PlayReady SDK calls that use the shared DRM_APP_CONTEXT from both system and session layers.
• prPlatformMutex_ — CriticalSection with reference counting protecting Drm_Platform_Initialize and Drm_Platform_Uninitialize in CPRDrmPlatform.
• prSessionMutex_ — CriticalSection protecting PlayreadySession::InitializeDRM during session-local context setup.
• SafeCriticalSection — RAII wrapper for WPEFramework::Core::CriticalSection providing scoped lock with explicit unlock() and relock() methods, used throughout in preference to manual lock/unlock pairs.
• Session Count Guard: m_sessionCount (in the PlayReady system class) tracks the number of live MediaKeySession instances. Both InitializeAppCtx() and UninitializeAppCtx() check this counter before resetting m_poAppContext, preventing a use-after-free where active sessions hold a raw alias of the app context pointer. m_isAppCtxInitialized is a complementary flag that prevents double-initialization.
• Async / Event Dispatch: Key status updates and key messages are delivered synchronously to the registered IMediaKeySessionCallback during Update(), Run(), and error paths. All callbacks are invoked inline on the calling thread.

Platform and Integration Requirements

• Build Dependencies: wpeframework, wpeframework-clientlibraries, wpeframework-tools-native, entservices-apis, gst-svp-ext, gstreamer1.0, OpenSSL. Platform-specific PlayReady library resolved via platform-playready-depends and platform-playready-flags Yocto variables.
• Component Dependencies: The WPEFramework OCDM Plugin (OpenCDMi) must be active; this OpenCDMi backend is loaded by the OCDM Plugin (OpenCDMi) at startup.
• SVP Integration: gst-svp-ext is used for secure memory allocation and token management during decryption. The gst-svp-ext generic interface delegates platform-specific SVP operations to the underlying platform HAL.
• Systemd Services: When run under systemd, the component's stdout/stderr logging can be captured by journald (depending on the unit configuration).
• Configuration Files: JSON configuration string delivered by the WPEFramework configuration system at component initialization, containing read-dir, store-location, and home-path fields.
• Startup Order: The component is loaded by the WPEFramework OCDM Plugin (OpenCDMi). svpPlatformInitializePlayready() is called at the start of Initialize() before any DRM context setup.

Component State Flow

Initialization to Active State

The component is initialized when the WPEFramework OCDM Plugin (OpenCDMi) calls Initialize() on the system object. Platform-level PlayReady initialization is performed first (svpPlatformInitializePlayready), followed by JSON configuration parsing to extract the DRM data directory and store paths. The DRM path globals are set, directories are created, and the revocation buffer is allocated in CreateSystemExt(). The DRM application context is then initialized via Drm_Initialize(). If the store is found to be corrupt, it is deleted and initialization is retried automatically. After successful context setup, the revocation buffer is registered, the secure or anti-rollback clock is validated, and the revocation list is loaded. Finally, expired and removal-date licenses are removed from the store.

The component transitions through the following states during its lifecycle: Initializing (platform init, config parse) → SystemExtCreated (DRM path and revocation buffer allocated) → AppCtxInitialized (Drm_Initialize succeeded, revocation buffer registered, clock validated, revocation list loaded) → Active (serving CDMi calls and session creation) → Shutdown (store cleanup, Drm_Uninitialize, platform uninit).

sequenceDiagram
    participant OCDM as WPEFramework OCDM Plugin (OpenCDMi)
    participant PR as PlayReady OCDM (OpenCDMi Backend)
    participant SVP as gst-svp-ext (Generic)
    participant PRSDK as PlayReady SDK (SoC DRM)

    OCDM->>PR: Initialize(shell, configline)
    PR->>SVP: svpPlatformInitializePlayready()
    SVP-->>PR: Platform ready

    PR->>PR: OnSystemConfigurationAvailable(configline)
    PR->>PR: Parse JSON config (read-dir, store-location, home-path)
    PR->>SVP: svpGetDrmStoragePath()
    SVP-->>PR: Store path resolved

    PR->>PR: CreateSystemExt() — set DRM path globals, alloc revocation buffer

    PR->>PRSDK: Drm_Platform_Initialize(platformInitData)
    PRSDK-->>PR: Platform initialized

    PR->>SVP: svpGetDrmOEMContext()
    SVP-->>PR: OEM context

    PR->>PRSDK: Drm_Initialize(AppCtx, OemCtx, opaqueBuf, storeNameStr)
    PRSDK-->>PR: DRM_SUCCESS (or store corrupt → delete & retry)

    PR->>PRSDK: Drm_Revocation_SetBuffer(revocationBuf, size)
    PRSDK-->>PR: OK

    PR->>SVP: svpIsSecureClockInitNeed()
    SVP-->>PR: bool

    PR->>PRSDK: Drm_SecureTime_GetValue() / Drm_AntiRollBackClock_Init()
    PRSDK-->>PR: Clock validated

    PR->>SVP: svpLoadRevocationList()
    SVP-->>PR: Revocation list loaded

    PR->>PRSDK: Drm_StoreMgmt_CleanupStore(DELETE_EXPIRED | DELETE_REMOVAL_DATE)
    PRSDK-->>PR: Store cleaned

    PR-->>OCDM: Initialization complete — Component Active

    loop Runtime
        OCDM->>PR: CDMi API calls (sessions, decrypt, secure stop)
    end

    OCDM->>PR: Deinitialize()
    PR->>PRSDK: Drm_StoreMgmt_CleanupStore()
    PR->>PRSDK: Drm_Uninitialize()
    PR->>PRSDK: Drm_Platform_Uninitialize()
    PR->>SVP: svpPlatformUninitializePlayready()
    PR-->>OCDM: Deinitialized

Runtime State Changes

State Change Triggers:

• A new MediaKeySession is created per content stream. Each session transitions independently through KEY_INIT → KEY_PENDING → KEY_READY → KEY_CLOSED. Update() guards its entry with a state check (KEY_PENDING required).
• If DRM_E_SECURESTORE_CORRUPT, DRM_E_SECURESTOP_STORE_CORRUPT, or DRM_E_DST_CORRUPTED are returned from Drm_Initialize, the store file is deleted and initialization is automatically retried once.
• On Close(), in-memory licenses (tracked by batch ID) and any temporary persistent licenses acquired during the session are deleted from the store.

Context Switching Scenarios:

• When the license server response contains persistent licenses, they are tracked per session and removed when the session closes, preventing accumulation in the store across playback sessions.
• When Drm_Reader_Bind returns DRM_E_BUFFERTOOSMALL, the opaque buffer is doubled (up to 64× its initial size) and the bind operation is retried, allowing the session to adapt to license complexity without failing.

Call Flows

Initialization Call Flow

sequenceDiagram
    participant OCDM as OCDM (OpenCDMi)
    participant PR as PlayReady OCDM (OpenCDMi Backend)
    participant SVP as gst-svp-ext (Generic)
    participant PRSDK as PlayReady SDK (SoC DRM)

    OCDM->>PR: Initialize(shell, configJSON)
    PR->>SVP: svpPlatformInitializePlayready()
    PR->>PR: Parse config (read-dir, store-location, home-path)
    PR->>SVP: svpGetDrmStoragePath(readDir, storePath, storeLocation)
    PR->>PR: CreateSystemExt() — set g_dstrDrmPath, alloc revocation buffer
    PR->>PRSDK: Drm_Platform_Initialize(platformInitData)
    PR->>SVP: svpGetDrmOEMContext()
    PR->>PRSDK: Drm_Initialize(AppCtx, OemCtx, opaqueBuf, storeNameStr)
    PR->>PRSDK: Drm_Revocation_SetBuffer(revocationBuf, REVOCATION_BUFFER_SIZE)
    PR->>PRSDK: Drm_SecureTime_GetValue() / Drm_AntiRollBackClock_Init()
    PR->>SVP: svpLoadRevocationList()
    PR->>PRSDK: Drm_StoreMgmt_CleanupStore(DELETE_EXPIRED | DELETE_REMOVAL_DATE)
    PR-->>OCDM: Ready

Session License Acquisition Call Flow

sequenceDiagram
    participant App as Application / WPE Runtime
    participant OCDM as OCDM (OpenCDMi)
    participant PR as PlayReady OCDM (OpenCDMi Backend)
    participant PRSDK as PlayReady SDK (SoC DRM)
    participant LS as License Server

    App->>OCDM: createMediaKeySession(initData)
    OCDM->>PR: CreateMediaKeySession(keySystem, initData, cdmData, ...)
    PR->>PR: parsePlayreadyInitializationData() — extract DRM header from PSSH
    PR->>PRSDK: Drm_Content_SetProperty(DRM_CSP_AUTODETECT_HEADER, drmHeader)
    PR->>PRSDK: DRM_HDR_GetAttribute() — extract Key IDs and header version
    PR-->>OCDM: MediaKeySession created (KEY_INIT)

    OCDM->>PR: Run(callback)
    PR->>PRSDK: Drm_LicenseAcq_GenerateChallenge(rights, customData, ..., &challenge, &batchID)
    PR-->>OCDM: callback.OnKeyMessage(challenge, silentURL)
    OCDM-->>App: keyMessage event (KEY_PENDING)

    App->>LS: POST challenge to license server
    LS-->>App: License response

    App->>OCDM: update(licenseResponse)
    OCDM->>PR: Update(licenseResponse)
    PR->>PRSDK: Drm_LicenseAcq_ProcessResponse(response, &licenseResponse)
    loop Per key acknowledgement in response
        PR->>PRSDK: Drm_Content_SetProperty(DRM_CSP_DECRYPTION_OUTPUT_MODE, HANDLE)
        PR->>PRSDK: Drm_Reader_Bind(rights, _PolicyCallback, &decryptContext)
        PR->>PRSDK: Drm_Reader_Commit(_PolicyCallback)
    end
    PR-->>OCDM: callback.OnKeyStatusUpdate("KeyUsable", keyId)
    PR-->>OCDM: callback.OnKeyStatusesUpdated()
    OCDM-->>App: keystatuseschange event (KEY_READY)

Decrypt Call Flow

sequenceDiagram
    participant OCDM as OCDM (OpenCDMi)
    participant PR as PlayReady OCDM (OpenCDMi Backend)
    participant SVP as gst-svp-ext (Generic)
    participant PRSDK as PlayReady SDK (SoC DRM)

    OCDM->>PR: Decrypt(inData, sampleInfo, properties)
    PR->>PR: Resolve current decrypt context by Key ID from sampleInfo
    PR->>SVP: svp_allocate_secure_buffers(pSVPContext, secBufInfo, encData, encDataLen)
    PR->>SVP: svp_buffer_alloc_token() / svp_buffer_to_token()
    PR->>PRSDK: Drm_Reader_DecryptMultipleOpaque(decryptContext, ivVector, regionMapping, encData)
    PRSDK-->>PR: decryptedLength, pDecryptedContent (secure handle)
    PR->>SVP: Write secure token to output buffer header
    PR-->>OCDM: CDMi_SUCCESS — output buffer contains SVP token

Internal Modules

Component Interactions

The component's interactions are with the WPEFramework OCDM Plugin — OpenCDMi (northbound, in-process), the PlayReady SDK / SoC DRM libraries (southbound, in-process), and gst-svp-ext (generic interface delegating to the platform SVP HAL) for secure memory management.

Interaction Matrix

Events Published

IPC Flow Patterns

Primary Request / Response Flow:

The WPEFramework OCDM Plugin (OpenCDMi) dispatches CDMi API calls directly in-process to the component's C++ interface. The component then invokes PlayReady SDK APIs synchronously under the protection of drmAppContextMutex_.

sequenceDiagram
    participant App as Application
    participant OCDM as OCDM (OpenCDMi)
    participant PR as PlayReady OCDM (OpenCDMi Backend)
    participant PRSDK as PlayReady SDK (SoC DRM)

    App->>OCDM: EME API call
    OCDM->>PR: CDMi method call (in-process)
    PR->>PRSDK: Drm_* API call (under drmAppContextMutex_)
    PRSDK-->>PR: DRM_RESULT
    PR-->>OCDM: CDMi_RESULT
    OCDM-->>App: EME result / event

Event Notification Flow:

Key status events are posted synchronously from within the Update() and playreadyGenerateKeyRequest() call paths by invoking the registered IMediaKeySessionCallback directly on the calling thread.

sequenceDiagram
    participant PRSDK as PlayReady SDK (SoC DRM)
    participant PR as PlayReady OCDM (OpenCDMi Backend)
    participant CB as IMediaKeySessionCallback
    participant App as Application

    PRSDK-->>PR: Drm_LicenseAcq_ProcessResponse() result
    PR->>CB: OnKeyStatusUpdate("KeyUsable", keyId)
    PR->>CB: OnKeyStatusesUpdated()
    CB-->>App: keystatuseschange event

Implementation Details

SDK and Component API Reference

PlayReady SDK APIs

Called by playready-rdk directly on SoC-provided PlayReady DRM libraries (path: playready-rdk → SoC DRM libraries).

gst-svp-ext Component APIs

Called by playready-rdk on the gst-svp-ext generic interface. GStreamer SVP-specific platform handling is passed through by gst-svp-ext to the underlying platform HAL layer (path: playready-rdk → gst-svp-ext generic → gst-svp-ext platform HAL).

Key Implementation Logic

• State / Lifecycle Management: MediaKeySession maintains a KeyState enum with values KEY_INIT, KEY_PENDING, KEY_READY, KEY_ERROR, and KEY_CLOSED. State transitions are driven by Run() (→ KEY_PENDING), Update() (→ KEY_READY or KEY_ERROR), and Close() (→ KEY_CLOSED). The entry guard ChkBOOL(m_eKeyState == KEY_PENDING) at the start of Update() prevents out-of-order license response processing.
• Core implementation: MediaSession.cpp

• State transition handlers: MediaSession.cpp (Run, Update, Close, playreadyGenerateKeyRequest)

• Dual Decrypt Context Binding: Each __DECRYPT_CONTEXT holds two DRM_DECRYPT_CONTEXT fields. During Update(), BindKeyNow(), and SelectKeyId(), if svpIsAudioNeedNonSVPContext() returns true, a second ReaderBind is performed with OEM_TEE_DECRYPTION_MODE_NOT_SECURE to populate oDrmDecryptAudioContext. During Decrypt(), the audio context is selected when useSVP is false.

• CBCS Pattern Handling: In the decrypt path, the encryptedRegionSkip vector (passed to Drm_Reader_DecryptMultipleOpaque as skip/pattern data) is populated conditionally: for AesCbc_Cbcs scheme the pattern is always pushed even when values are 0:0 (required for audio CBCS), whereas for all other schemes the pattern is only pushed when encrypted_blocks != 0.

• Event Processing: Events are dispatched synchronously to IMediaKeySessionCallback from within Update(), playreadyGenerateKeyRequest(), and error paths. Key status strings ("KeyUsable", "KeyOutputRestricted", "KeyOutputRestrictedHDCP", "KeyOutputRestrictedHDCP22", "LicenseExpired", "LicenseNotFound", "KeyInternalError") are mapped from DRM_RESULT values through MapDrToKeyMessage() in MediaSession.cpp.

• Error Handling Strategy: DRM_RESULT error codes are checked after every PlayReady SDK call. Non-fatal errors trigger retry logic:

• DRM_E_BUFFERTOOSMALL in ReaderBind causes the opaque buffer to be doubled (up to 64× its initial size) before retrying.
• DRM_E_BUFFERTOOSMALL in playreadyGenerateKeyRequest triggers a two-pass challenge generation to size the challenge buffer correctly.
• DRM_E_NO_URL from Drm_LicenseAcq_GenerateChallenge causes a silent retry of the same call with the URL output parameters set to nullptr, allowing challenge generation to proceed for content that carries no embedded license URL.
• DRM_E_LICACQ_TOO_MANY_LICENSES from Drm_LicenseAcq_ProcessResponse causes the acks array to be reallocated to the required size and the call to be retried once.
• Fatal errors set m_eKeyState = KEY_ERROR and invoke OnError() and OnKeyStatusUpdate() on the callback. Decrypt failures are handled in DRM_DecryptFailure(), which reports a hex-encoded error code string.

• Store corruption at Drm_Initialize (DRM_E_SECURESTORE_CORRUPT, DRM_E_SECURESTOP_STORE_CORRUPT, DRM_E_DST_CORRUPTED) triggers automatic store deletion and one retry.

• Logging & Diagnostics: All diagnostics are emitted through the PR_LOG(level, fmt, ...) macro introduced in this codebase. The macro emits to stderr with the format [PlayReady][LEVEL][function:line] message. Five levels are defined: PR_LOG_ERROR (0), PR_LOG_WARN (1), PR_LOG_INFO (2), PR_LOG_DEBUG (3), PR_LOG_TRACE (4). The active log level is held in the global g_logLevel and initialized at startup by InitializeLogLevel(), which reads the PLAYREADY_RDK_LOG_LEVEL environment variable. If the variable is absent or out of range the level defaults to PR_LOG_DEBUG. When DRM_ERROR_NAME_SUPPORT is enabled at build time, human-readable error name strings are appended to every DRM result log via DRM_ERR_GetErrorNameFromCode() through the DRM_ERR_NAME(dr) macro. DRM header bytes are logged at PR_LOG_TRACE level as a base64 string via a local convertToBase64() helper in MediaSessionExt.cpp.

Configuration

Key Configuration Files

Key Configuration Parameters

Runtime Configuration Parameters

Build-Time Configuration Parameters

Configuration Persistence

The DRM store file at the path specified by store-location persists license data across reboots and is managed by the PlayReady SDK. In-memory licenses and temporary persistent licenses acquired during a session are deleted from the store when that session is closed.