Overview

Content key policies are a critical component of content protection in Ravnur Media Services. A content key policy defines the conditions under which content decryption keys are delivered to end-user devices. By configuring content key policies, you control who can access your protected content and under what circumstances, enabling secure delivery of premium media while preventing unauthorized access.

What Are Content Key Policies?

A content key policy specifies the requirements that must be met before a content key is delivered to a client. Content keys are the encryption keys used to decrypt protected media content. The policy acts as a gatekeeper, ensuring only authorized users and devices can obtain the keys needed to play your content.

Key Components:

• Policy Name - Unique identifier for the content key policy
• Policy Options - One or more configurations that define different ways to deliver keys
• Restrictions - Requirements clients must meet (token validation, IP restrictions, etc.)
• Configuration - DRM-specific settings for PlayReady, Widevine, or FairPlay

Content key policies work in conjunction with streaming locators and streaming policies to create a complete content protection workflow. While the streaming policy defines which DRM systems are used, the content key policy defines who can access the decryption keys.

How Content Key Policies Work

When a player attempts to play protected content:

1. Content Request - The player requests the encrypted media from the streaming endpoint
2. License Request - The player identifies that content is encrypted and requests a license/key
3. Policy Evaluation - Ravnur Media Services evaluates the content key policy to determine if the client meets requirements
4. Token Validation - If required, the system validates any authentication tokens provided by the client
5. Key Delivery - If all requirements are met, the content key is delivered to the player
6. Decryption and Playback - The player uses the key to decrypt and play the content

This workflow ensures that only authorized clients can access your protected content.

Policy Options and Restrictions

Each content key policy can have multiple options, providing flexibility for different scenarios. Each option includes:

Configuration Type - Specifies the DRM system or encryption method:

• FairPlay - Apple's DRM system for iOS, tvOS, and Safari
• PlayReady - Microsoft's DRM system for Windows, Xbox, and other platforms
• Widevine - Google's DRM system for Android, Chrome, and other platforms
• Clear Key - Simple AES-128 envelope encryption without full DRM

Restriction Type - Defines who can obtain keys:

• Open Restriction - No authentication required; anyone can request keys (useful for testing)
• Token Restriction - Requires a valid JWT or SWT token for authentication
• IP Restriction - Limits key delivery to specific IP address ranges

Token Restrictions

Token restrictions are the most common and secure method for protecting content. They require clients to present a valid token when requesting a content key.

Token Types:

• JWT (JSON Web Token) - Industry-standard token format with JSON payload
• SWT (Simple Web Token) - Legacy format, less common but still supported

Token Claims: When using token restrictions, you specify required claims that must be present in the token, such as:

• User ID or subscription level
• Content ID or asset permissions
• Expiration time
• Custom business logic claims

Token Validation: Tokens must be signed with a key that you configure in the content key policy. Ravnur Media Services validates the signature and claims before delivering the content key.

Signing Keys:

• Symmetric Key - Shared secret used to both sign and verify tokens
• Asymmetric Keys (RSA) - Public/private key pair where the private key signs tokens and the public key verifies them
• X509 Certificate - Certificate-based signing for enhanced security

Example Token Workflow

1. User authenticates with your application or identity provider
2. Your backend generates a JWT token with required claims and signs it with your key
3. Your application passes the token to the media player
4. Player requests content key from Ravnur Media Services, presenting the token
5. Ravnur validates the token signature and claims against the content key policy
6. If valid, the content key is delivered; if invalid, access is denied

DRM-Specific Configurations

Each DRM system has specific configuration requirements within content key policies.

FairPlay Configuration

FairPlay is Apple's DRM system used on iOS, tvOS, macOS, and Safari browsers.

Required Elements:

• Application Certificate - FPS certificate obtained from Apple Developer portal
• Content Key - The encryption key used to encrypt your content
• Key Identifier - Unique identifier for the content key
• Rental Duration - Optional rental period for content

FairPlay Workflow: FairPlay uses a unique certificate-based system where you must obtain an FPS (FairPlay Streaming) certificate from Apple and configure it in your content key policy.

PlayReady Configuration

PlayReady is Microsoft's DRM system supporting Windows, Xbox, smart TVs, and various devices.

Configuration Options:

• License Type - Persistent (offline) or non-persistent (streaming only)
• Content Key Location - Embedded or referenced
• Play Right - Defines playback permissions and restrictions
• Analog Video OPL - Output protection level for analog video
• Digital Video OPL - Output protection level for digital video
• Digital Audio OPL - Output protection level for digital audio
• Expiration Settings - Absolute or duration-based license expiration

PlayReady License Template: PlayReady uses an XML-based license template that defines detailed rights and restrictions for content playback.

Widevine Configuration

Widevine is Google's DRM system widely used on Android devices, Chrome browsers, and smart TVs.

Security Levels:

• L1 (Hardware) - Highest security, uses hardware-backed key storage
• L3 (Software) - Software-based protection for devices without secure hardware

Configuration Options:

• Allowed Track Types - SD, HD, UHD content restrictions
• Content Key Specs - Defines track type, security level, and crypto period
• Policy Overrides - Rental duration, playback duration, license duration
• HDCP Requirements - Version requirements for HDCP output protection

Widevine License Template: Widevine uses a JSON-based template specifying content protection requirements and playback restrictions.

Creating and Managing Content Key Policies

Policy Creation

When creating a content key policy, you specify:

1. Policy Name - Unique identifier within your account
2. Description - Optional description of the policy's purpose
3. Options - One or more policy options with configurations and restrictions

Best Practice: Create separate policies for different content tiers or use cases (e.g., "premium-subscribers-policy", "rental-content-policy", "free-tier-policy").

Policy Reusability

Content key policies are designed to be reusable across multiple assets and streaming locators. You typically:

1. Create a small set of well-defined policies matching your business scenarios
2. Reference these policies when creating streaming locators for your assets
3. Avoid creating unique policies for each asset

This approach simplifies management and ensures consistent content protection across your content library.

Policy Association

Content key policies are associated with streaming locators. When you create a streaming locator with a DRM-enabled streaming policy, you specify which content key policy to use. The streaming locator then uses that policy to determine key delivery authorization.

Updating Policies

Content key policies cannot be modified after creation. If you need to change policy configuration:

1. Create a new content key policy with the desired settings
2. Create new streaming locators that reference the new policy
3. Delete old streaming locators (which invalidates existing access)
4. Optionally delete the old content key policy once it's no longer referenced

This immutability ensures that existing authorized access is not inadvertently modified.

Multi-DRM Scenarios

Modern content protection often requires supporting multiple DRM systems simultaneously to accommodate diverse client devices and platforms.

Common Multi-DRM Pattern

A typical multi-DRM content key policy includes multiple options:

Option 1 - FairPlay Configuration

• Configuration: FairPlay settings with your Apple certificate
• Restriction: Token restriction requiring valid JWT

Option 2 - PlayReady Configuration

• Configuration: PlayReady license template with your requirements
• Restriction: Token restriction with same validation key as FairPlay

Option 3 - Widevine Configuration

• Configuration: Widevine license template matching your security needs
• Restriction: Token restriction with same validation key as FairPlay/PlayReady

All three options use the same token validation approach, allowing a single token to authorize key delivery for any DRM system. The player automatically selects the appropriate DRM system based on device capabilities.

Benefits of Multi-DRM

Universal Device Support - Cover iOS, Android, Windows, game consoles, smart TVs, and web browsers

Consistent Security - Apply the same authorization logic across all DRM systems

Simplified Token Management - Use a single token format and validation approach

Future-Proofing - Easily add new DRM systems as device landscape evolves

Use Cases and Examples

Subscription Video Service

Scenario: Deliver premium content to paying subscribers only

Solution:

• Create content key policy with token restriction
• Generate JWT tokens for authenticated subscribers with subscription level claim
• Configure all three DRM systems (FairPlay, PlayReady, Widevine) with same token validation
• Set appropriate license expiration matching subscription renewal period

Rental Content

Scenario: Allow users to rent content for a limited time period (e.g., 48 hours)

Solution:

• Create content key policy with token restriction
• Generate JWT tokens with rental expiration claim
• Configure DRM licenses with rental duration settings
• Set license expiration to match rental period
• Use persistent licenses to allow offline viewing during rental period

Free Tier with Ads

Scenario: Provide content with ads to non-paying users, prevent unauthorized redistribution

Solution:

• Create content key policy with token restriction
• Generate JWT tokens for all authenticated users (even free tier)
• Configure basic DRM protection to prevent casual piracy
• Use less restrictive output protection levels
• Shorter license durations to ensure ad refresh

Educational Content

Scenario: Distribute educational videos to enrolled students only

Solution:

• Create content key policy with token restriction
• Generate JWT tokens with student ID and course enrollment claims
• Configure licenses to prevent offline storage beyond course duration
• Set appropriate output protection for classroom display scenarios

Live Event PPV (Pay-Per-View)

Scenario: Secure live streaming event requiring payment

Solution:

• Create content key policy with token restriction
• Generate JWT tokens upon payment confirmation
• Set license expiration to match event duration plus reasonable buffer
• Use non-persistent licenses (streaming only)
• Monitor for suspicious access patterns

Testing and Development

Open Restriction for Testing

During development, you can create content key policies with open restrictions (no authentication required) to simplify testing:

• Test DRM integration without token generation complexity
• Verify playback across different devices and players
• Debug license acquisition workflows

Important: Never use open restrictions in production environments as they allow unrestricted access to content keys.

Test Tokens

For testing token-based policies:

• Create a separate content key policy with token restrictions using test signing keys
• Generate test tokens with various claims and expiration times
• Verify proper token validation and rejection scenarios
• Test token expiration handling in your players

Security Best Practices

✅ Use Strong Signing Keys - Generate cryptographically strong keys for token signing (256-bit minimum for symmetric, 2048-bit minimum for RSA)

✅ Rotate Keys Regularly - Periodically update signing keys and content key policies to limit exposure if a key is compromised

✅ Implement Token Expiration - Always set reasonable token expiration times (hours to days, not weeks or months)

✅ Validate All Claims - Include and validate all necessary claims in tokens (user ID, content permissions, subscription status)

✅ Use HTTPS Everywhere - Ensure all communication between clients and your services uses TLS/HTTPS

✅ Monitor License Requests - Track license acquisition patterns to detect abnormal behavior or potential attacks

✅ Implement Rate Limiting - Limit license request frequency from individual clients to prevent abuse

✅ Separate Test and Production - Use different signing keys and policies for development and production environments

✅ Secure Key Storage - Store signing keys in secure key management systems, never in application code

✅ Audit Access Regularly - Review who has access to content key policy configurations and signing keys

Limitations and Considerations

Policy Immutability - Content key policies cannot be modified after creation; you must create new policies for changes

Token Size Limits - Very large tokens with many claims may exceed size limits in some scenarios; keep tokens concise

Clock Synchronization - Token expiration validation requires accurate system clocks; ensure NTP synchronization

DRM Platform Limitations - Each DRM system has specific device, browser, and OS requirements that may limit reach

License Caching - Clients may cache licenses; expiration enforcement depends on client behavior and license settings

Performance Impact - Token validation and license generation add latency; design for acceptable response times

Costs - DRM license delivery incurs costs based on the number of licenses issued; monitor usage

Related Topics

For more information about related concepts, see:

• Streaming Policies
• Streaming Locators
• Content Encryption
• DRM Systems (FairPlay, PlayReady, Widevine)
• Token Authentication (JWT, SWT)
• Assets

For detailed implementation guidance for your specific Ravnur Media Services deployment, including code examples and API references, consult your technical documentation or contact your Ravnur support team.