How To - Multiscreen Key Management Server (KMS) Interface

  • 1
  • Question
  • Updated 2 years ago
  • Answered
  • (Edited)
Introduction Harmonic KMS interface is a XML/SOAP-based interface designed to facilitate encryption key and DRM metadata exchange between an OTT packager/scrambler and Key Management Server. 

This page is meant to describe the general process for DRM partners wishing to integrate VOS 360 and VOS Cloud via Harmonic KMS interface, providing key consideration topics, troubleshooting tips, and links to relevant specifications

This page is NOT meant to define any specifications, please refer to the References section for links to API specification documents.


The interface is applicable for the following ABR formats and encryption types:

As seen in the table, different formats/encryption methods may require different KMS API methods. Within specific API methods, there may also be format-specific signalization structures to provide the necessary metadata required for each format. *key rotation not supported due to format-specific limitation

Special notes for Apple HLS/FairPlay DRM

Some custom attributes are mandatory in the GetKeyAndSignalization response when using Apple FairPlay DRM. See example in Sample Exchange section below.   KEYFORMAT

   This attribute is mandatory and shall be “”.


   This attribute is mandatory and shall be “1”.


   This attribute is mandatory.

Special notes for Smooth Streaming/PlayReady DRM with key rotation

In Smooth Streaming encryption, the manifestHeader represents the ProtectionSystem header included in the Smooth Streaming manifest. It is mandatory for KMS to provide this in the GetKeyAndSignalization response.

Implementation Best Practices/Guidelines

  1. For encryption methods utilizing more than one API method, KMS must not assume a fixed ordering in which calls are made. For example, GetKey and GetClientParameters can be called in either order.
  2. When multiple formats/encryption methods are required for a single service, it may be desirable to include a suffix on the ResourceID to differentiate between key requests for different formats which may have different response fields. For example, since both HLS/AES and SS/PlayReady share the same GetKey method, appending a suffix of "_HLS" or "_SS" to a common ResourceID base string would remove any ambiguity for KMS to return the corresponding DRM data for either formats.
  3. The original KMS API specifications document describes a Full and Minimum Implementation - we recommend the Minimum Implementation. While the Full Implementation provides the benefit of an additional Key Session layer for redundancy and horizontal scaling, there may already be pre-existing redundancy/scaling methods within the DRM implementation such that the simplicity of the Minimum Implementation makes it an overall better approach.
  4. element returned in GetClientParameters and GetKeyAndSignalization responses must be in big endian UUID format.

General Integration Process
    1. DRM partner on-boarding
      1. (Harmonic) Provide KMS API documents
      2. (Harmonic) Provide VOS 360 testing environment access
    2. (Joint) Discussions and Q&A session with partner for interface clarifications
    3. (Partner) Self-service testing against provided VOS 360 testing environment. Once deemed acceptable, proceed to step 4.
    4. (Partner) Provide internet-accessible KMS Server URL, version tracking, list of authorized ResourceID's and RequestorID's, Signer(if applicable). If possible, also share any special clients that may be required to playback the encrypted content.
    5. (Harmonic) Perform sanity check with provided URL and ID's, record integration status with partner code versions documented. If client is available, attempt playback of encrypted streams.

    Expected System Behavior
      • Upon service provisioning, VOS 360 will generate KMS key requests to DRM partner-provided KMS endpoint to retrieve encryption keys. Upon success key retrieval, the encrypted content is produced and published to the Destination server.
      • DRM partner should visually verify and/or provide clients to verify the encrypted content for successful playback.
      • VOS 360 should provide useful alarms/notifications upon encountering key retrieval failure to ease troubleshooting.

      Sample Exchange

      HLS/Native AES

      HLS/Apple FairPlay

      DASH/Common Encryption(PlayReady + Widevine)

      Smooth Streaming/PlayReady (No key rotation)

      Smooth Streaming/PlayReady (Key rotation)

      FAQ Frequently Asked Questions

      Q. What port number should the KMS service run on? A. VOS 360 does not require the KMS service to run on a specific port number, though KMS vendor should ensure necessary firewall rules are configured to allow VOS 360 to reach the KMS endpoint.


      Q. Does VOS 360 support HTTPS/SSL?

      A. Yes! Use of HTTPS is recommended for security reasons to mitigate risks of Man-in-the-middle(MITM) attacks. However, during initial integrations/development phase, it may be desirable to make available a HTTP endpoint to allow network capturing to identify possible problems in the KMS communications.


      Q. Is it required for unique ResourceID between services?

      A. It is not a strict requirement in VOS 360 to have unique ResourceIDs, but in order to have different keys for each service, unique ResourceIDs are recommended per service.


      Q. Is it required for unique ResourceID between different package formats/encryption methods within the SAME service?

      A. As different formats may have some format-specific requirements, having unique ResourceIDs or appending a suffix to the end of a common ResourceID would help KMS differentiate between multiple package formats and return the relevant DRM metadata for each. For example:





      Q. In a key rotation scenario, how often does VOS 360 make key requests to the KMS endpoint?

      A. The key rotation interval configuration determines the frequency of making key requests. Currently, VOS 360 does not yet support multiple keys per request(although the multiple ScheduledKey structure is defined in the KMS spec, it is for future consideration only).


      Q. For key rotation, how does VOS 360 identify the key being requested for a given time window?

      A. Within the GetKey or GetKeyAndSignalization methods, there is a parameter which denotes the time period for which the key is being requested. For live streams, the time is the POSIX time in seconds.(IEEE Std 1003 Committee, 2008).


      Q. Is it expected for KMS vendor to provide a single shared KMS endpoint for multiple VOS 360 customers? Or a single endpoint per customer?

      A. VOS 360 does not have restrictions on KMS endpoints sharing, though for manageability and tracking purposes, it may be desirable to segregate endpoints on a per customer basis.
      Photo of Ofer Aharon

      Ofer Aharon, Product Manager

      • 664 Points 500 badge 2x thumb

      Posted 2 years ago

      • 1

      Be the first to post a reply!