android/libwvdrmengine/cdm/core/src/device_files.proto

// ----------------------------------------------------------------------------
// device_files.proto
// ----------------------------------------------------------------------------
// Copyright 2018 Google LLC. All Rights Reserved. This file and proprietary
// source code may only be used and distributed under the Widevine License
// Agreement.
//
// Description:
//   Format of various files stored at the device.
//
syntax = "proto2";

package video_widevine_client.sdk;

// need this if we are using libprotobuf-cpp-2.3.0-lite
option optimize_for = LITE_RUNTIME;

message NameValue {
  optional string name = 1;
  optional string value = 2;
}

message DeviceCertificate {
  enum PrivateKeyType {
    RSA = 0;
    ECC = 1;
  }
  optional bytes certificate = 1;
  optional bytes wrapped_private_key = 2;
  optional PrivateKeyType key_type = 3 [default = RSA];
  // Used by DRM certificates with an expiry time. Set by the client when
  // the certificate is received. Aids expiration calculation at the
  // client when provisioning server and client clocks are not aligned
  optional int64 acquisition_time_seconds = 4;
  // Used by DRM certificates without an expiration time. This is for
  // upgrading devices with pre-existing DRM certificates. The client will
  // calculate an expiration time 6 months into the future with a randomized
  // +/-2 month window
  optional int64 expiration_time_seconds = 5;
}

message License {
  enum LicenseState {
    ACTIVE = 1;
    RELEASING = 2;
  }

  optional LicenseState state = 1;
  optional bytes pssh_data = 2;
  // |license_request|, |license|, |renewal_request|, |renewal| represents a
  // serialized video_widevine::SignedMessage containing a
  // video_widevine::License or video_widevine::LicenseRequest from
  // license_protocol.proto
  optional bytes license_request = 3;
  optional bytes license = 4;
  optional bytes renewal_request = 5;
  optional bytes renewal = 6;
  optional bytes release_server_url = 7;
  optional int64 playback_start_time = 8 [default = 0];
  optional int64 last_playback_time = 9 [default = 0];
  repeated NameValue app_parameters = 10;
  // This will be 0/missing if the grace period has not expired; otherwise it
  // contains the playback_start_time we should use as an override.  This is
  // ignored if there is no grace period.
  optional int64 grace_period_end_time = 11 [default = 0];
  optional bytes usage_entry = 12;
  optional int64 usage_entry_number = 13;
  optional DeviceCertificate drm_certificate = 14;
}

message UsageInfo {
  message ProviderSession {
    optional bytes token = 1;
    optional bytes license_request = 2;
    // |license| represents a video_widevine::SignedMessage containing a
    // video_widevine::License from license_protocol.proto
    optional bytes license = 3;
    optional bytes key_set_id = 4;
    optional bytes usage_entry = 5;
    optional int64 usage_entry_number = 6;
    // If not present, use the legacy DRM certificate rather than
    // one in DrmDeviceCertificate
    optional uint32 drm_certificate_id = 7;
  }

  // A cache of DeviceCertificates associated with usage entries
  message DrmUsageCertificate {
    optional uint32 drm_certificate_id = 1;
    optional DeviceCertificate drm_certificate = 2;
  }

  repeated ProviderSession sessions = 1;
  repeated DrmUsageCertificate drm_certificate_cache = 2;
}

message HlsAttributes {
  enum Method {
    AES_128 = 1;
    SAMPLE_AES = 2;
  }
  optional Method method = 1;
  optional bytes media_segment_iv = 2;
}

message UsageTableInfo {
  message UsageEntryInfo {
    enum UsageEntryStorage {
      LICENSE = 1;
      USAGE_INFO = 2;
      UNKNOWN = 3;
    }

    optional UsageEntryStorage storage = 1;
    optional bytes key_set_id = 2;
    optional bytes usage_info_file_name = 3;  // hash of the app_id

    // LRU table replacement data.
    optional int64 last_use_time = 4 [default = 0];
    // Only used if storage == LICENSE (offline license).
    optional int64 offline_license_expiry_time = 5 [default = 0];
  }

  optional bytes usage_table_header = 1;
  repeated UsageEntryInfo usage_entry_info = 2;
  optional bool use_lru = 3 [default = false];
}

// Stores information related to a device's experience with OTA Keybox
// Provisioning (OKP).  Only devices which both support OKP and require
// OKP should create this file.  Otherwise, this information is not
// needed.
message OtaKeyboxProvisioningInfo {
  // Engine-specific information about OKP.
  message OkpEngineInfo {
    // Engine identifier.
    optional bytes app_id = 1;
    optional bytes origin = 2;
    reserved 3 to 5;  // Reserved for future engine composite keys.
    // Counters for engine-specific OKP events.
    // These counters are reset after a certain amount of time
    // (OKP period) since the last event.
    // Number of calls to openSession() where it is recommended
    // to the app to try keybox provisioning.
    optional uint32 try_okp_counter = 6;
    // Number of calls to getProvisionRequest().
    optional uint32 generate_request_counter = 7;
    // Number of failed calls to provideProvisionRequest().
    optional uint32 failed_response_counter = 8;

    // The value of |last_event_time| and |backoff_start_time| are set
    // using the system's wall-clock in epoch seconds.  A value of
    // zero indicates it's not set.

    // Time of the last engine OKP event (change of the above counters;
    // the beginning of the current OKP period).
    // Zero indicates no event has yet occurred.
    optional int64 last_event_time = 9;
    // Beginning of an app/origin backoff period.
    // Zero indicates that engine is not in a backoff state.
    optional int64 backoff_start_time = 10;
    // Intended length of “backoff period”.  This will be assigned a
    // random duration initially, then double each time an engine
    // enters a backoff state.  This is base on Google's recommended
    // exponential backoff rules.
    // Value of 0 indicates that backoff has not yet occurred.
    optional int64 backoff_duration = 11;
  }

  enum OkpDeviceState {
    // Not yet checked for provisioning state.  This should be a
    // transitory state only.  Device which do not need OTA Keybox
    // Provisioning should simply not store this file.
    OKP_UNKNOWN = 0;
    // OEMCrypto has reported that keybox provisioning is required and
    // that the device supports OKP.  Device may or may not be in the
    // process of performing provisioning.
    OKP_NEEDS_PROVISIONING = 1;
    // The device has successfully provisioned its keybox.
    OKP_PROVISIONED = 2;
  }
  // Device-wide OKP state.
  optional OkpDeviceState state = 1;
  // Time when the CDM service first discovers that it needs to
  // provision the L1 keybox.
  optional int64 first_checked_time = 2;
  // System time of when a successful provisioning request has been
  // received.  Only relevant if |state| is OKP_PROVISIONED.
  optional int64 provisioning_time = 3;
  // A list of all records for each identifiable engine.
  repeated OkpEngineInfo engine_infos = 4;
}

message File {
  enum FileType {
    DEVICE_CERTIFICATE = 1;
    LICENSE = 2;
    USAGE_INFO = 3;
    HLS_ATTRIBUTES = 4;
    USAGE_TABLE_INFO = 5;
    OKP_INFO = 6;
  }

  enum FileVersion { VERSION_1 = 1; }

  optional FileType type = 1;
  optional FileVersion version = 2 [default = VERSION_1];
  optional DeviceCertificate device_certificate = 3;
  optional License license = 4;
  optional UsageInfo usage_info = 5;
  optional HlsAttributes hls_attributes = 6;
  optional UsageTableInfo usage_table_info = 7;
  optional OtaKeyboxProvisioningInfo okp_info = 8;
}

message HashedFile {
  optional bytes file = 1;
  // A raw (not hex-encoded) SHA256, taken over the bytes of 'file'.
  optional bytes hash = 2;
}