////////////////////////////////////////////////////////////////////////////////
// Copyright 2017 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.
////////////////////////////////////////////////////////////////////////////////
//
// Declaration of protocol buffer which is used to encode the data stored in
// Common Encryption (CENC) 'pssh' box Data fields.

syntax = "proto2";

package widevine;
option java_package = "com.google.video.widevine.protos";

message WidevinePsshData {
  enum Type {
    SINGLE = 0;        // Single PSSH to be used to retrieve content keys.
    ENTITLEMENT = 1;   // Primary PSSH used to retrieve entitlement keys.
    ENTITLED_KEY = 2;  // Secondary PSSH containing entitled key(s).
  }

  message EntitledKey {
    // ID of entitlement key used for wrapping |key|.
    optional bytes entitlement_key_id = 1;
    // ID of the entitled key.
    optional bytes key_id = 2;
    // Wrapped key. Required.
    optional bytes key = 3;
    // IV used for wrapping |key|. Required.
    optional bytes iv = 4;
    // Size of entitlement key used for wrapping |key|.
    optional uint32 entitlement_key_size_bytes = 5 [default = 32];
  }

  // Entitlement or content key IDs. Can onnly present in SINGLE or ENTITLEMENT
  // PSSHs. May be repeated to facilitate delivery of multiple keys in a
  // single license. Cannot be used in conjunction with content_id or
  // group_ids, which are the preferred mechanism.
  repeated bytes key_ids = 2;

  // Content identifier which may map to multiple entitlement or content key
  // IDs to facilitate the delivery of multiple keys in a single license.
  // Cannot be present in conjunction with key_ids, but if used must be in all
  // PSSHs.
  optional bytes content_id = 4;

  // Crypto period index, for media using key rotation. Always corresponds to
  // The content key period. This means that if using entitlement licensing
  // the ENTITLED_KEY PSSHs will have sequential crypto_period_index's, whereas
  // the ENTITELEMENT PSSHs will have gaps in the sequence. Required if doing
  // key rotation.
  optional uint32 crypto_period_index = 7;

  // Protection scheme identifying the encryption algorithm. The protection
  // scheme is represented as a uint32 value. The uint32 contains 4 bytes each
  // representing a single ascii character in one of the 4CC protection scheme
  // values. To be deprecated in favor of signaling from content.
  // 'cenc' (AES-CTR) protection_scheme = 0x63656E63,
  // 'cbc1' (AES-CBC) protection_scheme = 0x63626331,
  // 'cens' (AES-CTR pattern encryption) protection_scheme = 0x63656E73,
  // 'cbcs' (AES-CBC pattern encryption) protection_scheme = 0x63626373.
  optional uint32 protection_scheme = 9;

  // Optional. For media using key rotation, this represents the duration
  // of each crypto period in seconds.
  optional uint32 crypto_period_seconds = 10;

  // Type of PSSH. Required if not SINGLE.
  optional Type type = 11 [default = SINGLE];

  // Key sequence for Widevine-managed keys. Optional.
  optional uint32 key_sequence = 12;

  // Group identifiers for all groups to which the content belongs. This can
  // be used to deliver licenses to unlock multiple titles / channels.
  // Optional, and may only be present in ENTITLEMENT and ENTITLED_KEY PSSHs, and
  // not in conjunction with key_ids.
  repeated bytes group_ids = 13;

  // Copy/copies of the content key used to decrypt the media stream in which
  // the PSSH box is embedded, each wrapped with a different entitlement key.
  // May also contain sub-licenses to support devices with OEMCrypto 13 or
  // older. May be repeated if using group entitlement keys. Present only in
  // PSSHs of type ENTITLED_KEY.
  repeated EntitledKey entitled_keys = 14;

  ////////////////////////////  Deprecated Fields  ////////////////////////////
  enum Algorithm {
    UNENCRYPTED = 0;
    AESCTR = 1;
  };
  optional Algorithm algorithm = 1 [deprecated = true];
  optional string provider = 3 [deprecated = true];
  optional string track_type = 5 [deprecated = true];
  optional string policy = 6 [deprecated = true];
  optional bytes grouped_license = 8 [deprecated = true];
}