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 OemCertificate {
  enum PrivateKeyType {
    RSA = 0;
    ECC = 1;
  }
  optional bytes certificate = 1;
  optional bytes wrapped_private_key = 2;
  optional PrivateKeyType key_type = 3 [default = RSA];
}

// DRM certificate.
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_index = 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_index = 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 table_header = 1;
  repeated UsageEntryInfo entry_info_list = 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 {
  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;
    // Device still needs provisioning, but has reached a condition
    // where it should backoff from attempting OKP for a period of
    // time.
    OKP_FALLBACK_MODE = 2;
    // The device has successfully provisioned its keybox.
    OKP_PROVISIONED = 3;
  }
  // 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;
  // Beginning of a backoff period.
  // Zero indicates that engine is not in a backoff state.
  optional int64 backoff_start_time = 3;
  // 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 based on Google's recommended exponential
  // backoff rules.
  // Value of 0 indicates that backoff has not yet occurred.
  optional int64 backoff_duration = 4;
  // System time of when a successful provisioning request has been
  // received.  Only relevant if |state| is OKP_PROVISIONED.
  optional int64 provisioning_time = 5;
}

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

  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;
  optional OemCertificate oem_certificate = 9;
}

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