Content key policies are a critical component of content protection in Ravnur Media Services (RMS). 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.
In this article:
What are Content Key Policies?
Policy options and restrictions
Creating and managing Content Key Policies
Limitations and considerations
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 сomponents:
- 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:
- Content request - The player requests the encrypted media from the streaming endpoint.
- License request - The player identifies that content is encrypted and requests a license/key.
- Policy evaluation - RMS evaluates the content key policy to determine if the client meets requirements.
- Token validation - If required, the system validates any authentication tokens provided by the client.
- Key delivery - If all requirements are met, the content key is delivered to the player.
- 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. RMS 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
- User authenticates with your application or identity provider.
- Your backend generates a JWT token with required claims and signs it with your key.
- Your application passes the token to the media player.
- Player requests content key from RMS, presenting the token.
- Ravnur validates the token signature and claims against the content key policy.
- 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:
- Policy name - Unique identifier within your account.
- Description - Optional description of the policy's purpose.
- 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:
- Create a small set of well-defined policies matching your business scenarios.
- Reference these policies when creating streaming locators for your assets.
- 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:
- Create a new content key policy with the desired settings.
- Create new streaming locators that reference the new policy.
- Delete old streaming locators (which invalidates existing access).
- 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.