media_cas_packager_sdk_source/protos/public/media_cas.proto

////////////////////////////////////////////////////////////////////////////////
// Copyright 2018 Google LLC.
//
// This software is licensed under the terms defined in the Widevine Master
// License Agreement. For a copy of this agreement, please contact
// widevine-licensing@google.com.
////////////////////////////////////////////////////////////////////////////////


syntax = "proto2";

package widevine.cas;

// Widevine private data in the CA descriptor.
message CaDescriptorPrivateData {
  // Provider name.
  optional string provider = 1;

  // Content ID.
  optional bytes content_id = 2;

  // Deprecated.
  repeated bytes deprecated_entitlement_key_ids = 3;

  // The groups ids this channel belongs to.
  repeated bytes group_ids = 4;
}

// Widevine fingerprinting.
message Fingerprinting {
  // Channels that will be applied with the controls.
  repeated bytes channels = 1;
  // Fingerprinting controls are opaque to Widevine.
  optional bytes control = 2;
}

// Widevine service blocking.
message ServiceBlocking {
  // Channels that will be blocked.
  repeated bytes channels = 1;
  // Device groups that will be blocked. Group definition is opaque to Widevine.
  repeated bytes device_groups = 2;
  // Blocking start time in seconds since epoch. Start time is "immediate" if
  // this field is not set.
  optional int64 start_time_sec = 3;
  // Required. Blocking end time in seconds since epoch.
  optional int64 end_time_sec = 4;
}

// The payload field for an EMM.
message EmmPayload {
  repeated Fingerprinting fingerprinting = 1;
  repeated ServiceBlocking service_blocking = 2;
  // Epoch time in seconds. The time when the EMM is generated.
  optional int64 timestamp_secs = 3;
}

message SignedEmmPayload {
  // Serialized EmmPayload.
  optional bytes serialized_payload = 1;
  // ECC (Elliptic Curve Cryptography) signature of |serialized_payload|.
  optional bytes signature = 2;
}

message EcmMetaData {
  enum CipherMode {
    UNSPECIFIED = 0;
    AES_CBC = 1;
    AES_CTR = 2;
    DVB_CSA2 = 3;
    DVB_CSA3 = 4;
    AES_OFB = 5;
    AES_SCTE52 = 6;
    AES_ECB = 7;
  }
  // Required. The cipher mode used to encrypt/decrypt the content.
  optional CipherMode cipher_mode = 1;
  // Optional. The minimum age required to watch the content. The value
  // represents actual age, with 0 means no restriction.
  optional uint32 age_restriction = 2 [default = 0];
  // If specified, it means entitlement key rotation is enabled. The value will
  // be included in the license request. The server is expected to return
  // entitlement keys accordingly (e.g., keys for |entitlement_period_index| and
  // |entitlement_period_index| + 1).
  optional uint32 entitlement_period_index = 3;
  // Used only if entitlement key rotation is enabled. This parameter controls
  // the probability of requesting a new license by clients upon receiving this
  // ECM. The purpose is to spread out requests to avoid request storms. A
  // client will request a new license with possibility = 1 /
  // |entitlement_rotation_window_left|.
  optional uint32 entitlement_rotation_window_left = 4 [default = 1];
}

message EcmKeyData {
  // The wrapped content key data (aka control word).
  // Required.
  optional bytes wrapped_key_data = 1;
  // The ID of the entitlement key used to wrap the content key. The secure key
  // data associated with this ID is held by the license server. The client gets
  // the key from the license server through a license request.
  // Required for the even key data, optional for the odd key data if it is the
  // same as the even key data.
  optional bytes entitlement_key_id = 2;
  // IV for decrypting the wrapped_key_data.
  // Required for the even key data, optional for the odd key data if it is the
  // same as the even key data.
  optional bytes wrapped_key_iv = 3;
  // IV for decrypting the content stream.
  // Optional. If not specified in the even key data, 8 bytes 0x00 will be used;
  // If not specified in the odd key data, the same content iv in the even key
  // data will be used.
  optional bytes content_iv = 4;
}

message EcmGroupKeyData {
  // Group id of this key data.
  optional bytes group_id = 1;
  // Required. The key data for the even slot. Fields wrapped_key_iv and
  // content_iv may be omitted if it is the same as EcmPayload.even_key_data.
  optional EcmKeyData even_key_data = 2;
  // Optional. The key data for the odd slot if key rotation is enabled. Fields
  // wrapped_key_iv and content_iv may be omitted if it is the same as
  // EcmPayload.odd_key_data.
  optional EcmKeyData odd_key_data = 3;
}

message EcmPayload {
  // Required. Meta info carried by the ECM.
  optional EcmMetaData meta_data = 1;
  // Required. The key data for the even slot.
  optional EcmKeyData even_key_data = 2;
  // Optional. The key data for the odd slot if key rotation is enabled.
  optional EcmKeyData odd_key_data = 3;
  // Optional. Widevine fingerprinting information.
  optional Fingerprinting fingerprinting = 4;
  // Optional. Widevine service blocking information.
  optional ServiceBlocking service_blocking = 5;
  // If a channel belongs to a group, the content keys can additionally be
  // encrypted by the group entitlement keys.
  repeated EcmGroupKeyData group_key_data = 6;
}

// The payload field for an ECM with signature.
message SignedEcmPayload {
  // Serialized EcmPayload.
  optional bytes serialized_payload = 1;
  // ECC (Elliptic Curve Cryptography) signature of |serialized_payload|.
  optional bytes signature = 2;
}