media_cas_proxy_sdk/protos/public/license_protocol.proto

////////////////////////////////////////////////////////////////////////////////
// Copyright 2016 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.
////////////////////////////////////////////////////////////////////////////////
//
// Description:
//   Definitions of the protocol buffer messages used in the Widevine license
//   exchange protocol, described in Widevine license exchange protocol document
// TODO(user): find out a right way to strip out all the doc link.

syntax = "proto2";

package widevine;

import "protos/public/client_identification.proto";
import "protos/public/remote_attestation.proto";

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

// option optimize_for = LITE_RUNTIME;
enum LicenseType {
  STREAMING = 1;
  OFFLINE = 2;
}

enum PlatformVerificationStatus {
  // The platform is not verified.
  PLATFORM_UNVERIFIED = 0;
  // Tampering detected on the platform.
  PLATFORM_TAMPERED = 1;
  // The platform has been verified by means of software.
  PLATFORM_SOFTWARE_VERIFIED = 2;
  // The platform has been verified by means of hardware (e.g. secure boot).
  PLATFORM_HARDWARE_VERIFIED = 3;
  // Platform verification was not performed.
  PLATFORM_NO_VERIFICATION = 4;
  // Platform and secure storage capability have been verified by means of
  // software.
  PLATFORM_SECURE_STORAGE_SOFTWARE_VERIFIED = 5;
}

// LicenseIdentification is propagated from LicenseRequest to License,
// incrementing version with each iteration.
message LicenseIdentification {
  optional bytes request_id = 1;
  optional bytes session_id = 2;
  optional bytes purchase_id = 3;
  optional LicenseType type = 4;
  optional int32 version = 5;
  optional bytes provider_session_token = 6;
}

message License {
  // LINT.IfChange
  message Policy {
    // Indicates that playback of the content is allowed.
    optional bool can_play = 1 [default = false];

    // Indicates that the license may be persisted to non-volatile
    // storage for offline use.
    optional bool can_persist = 2 [default = false];

    // Indicates that renewal of this license is allowed.
    optional bool can_renew = 3 [default = false];

    // For the |*duration*| fields, playback must halt when
    // license_start_time (seconds since the epoch (UTC)) +
    // license_duration_seconds is exceeded. A value of 0
    // indicates that there is no limit to the duration.

    // Indicates the rental window.
    optional int64 rental_duration_seconds = 4 [default = 0];

    // Indicates the viewing window, once playback has begun.
    optional int64 playback_duration_seconds = 5 [default = 0];

    // Indicates the time window for this specific license.
    optional int64 license_duration_seconds = 6 [default = 0];

    // The |renewal*| fields only apply if |can_renew| is true.

    // The window of time, in which playback is allowed to continue while
    // renewal is attempted, yet unsuccessful due to backend problems with
    // the license server.
    optional int64 renewal_recovery_duration_seconds = 7 [default = 0];

    // All renewal requests for this license shall be directed to the
    // specified URL.
    optional string renewal_server_url = 8;

    // How many seconds after license_start_time, before renewal is first
    // attempted.
    optional int64 renewal_delay_seconds = 9 [default = 0];

    // Specifies the delay in seconds between subsequent license
    // renewal requests, in case of failure.
    optional int64 renewal_retry_interval_seconds = 10 [default = 0];

    // Indicates that the license shall be sent for renewal when usage is
    // started.
    optional bool renew_with_usage = 11 [default = false];

    // Indicates to client that license renewal and release requests ought to
    // include ClientIdentification (client_id).
    optional bool always_include_client_id = 12 [default = false];

    // Duration of grace period before playback_duration_seconds (short window)
    // goes into effect. Optional.
    optional int64 play_start_grace_period_seconds = 13 [default = 0];

    // Enables "soft enforcement" of playback_duration_seconds, letting the user
    // finish playback even if short window expires. Optional.
    optional bool soft_enforce_playback_duration = 14 [default = false];
  }

  message KeyContainer {
    enum KeyType {
      SIGNING = 1;           // Exactly one key of this type must appear.
      CONTENT = 2;           // Content key.
      KEY_CONTROL = 3;       // Key control block for license renewals. No key.
      OPERATOR_SESSION = 4;  // wrapped keys for auxiliary crypto operations.
      ENTITLEMENT = 5;       // Entitlement keys.
      OEM_CONTENT = 6;       // Partner-specific content key.
    }

    // The SecurityLevel enumeration allows the server to communicate the level
    // of robustness required by the client, in order to use the key.
    enum SecurityLevel {
      // Software-based whitebox crypto is required.
      SW_SECURE_CRYPTO = 1;

      // Software crypto and an obfuscated decoder is required.
      SW_SECURE_DECODE = 2;

      // The key material and crypto operations must be performed within a
      // hardware backed trusted execution environment.
      HW_SECURE_CRYPTO = 3;

      // The crypto and decoding of content must be performed within a hardware
      // backed trusted execution environment.
      HW_SECURE_DECODE = 4;

      // The crypto, decoding and all handling of the media (compressed and
      // uncompressed) must be handled within a hardware backed trusted
      // execution environment.
      HW_SECURE_ALL = 5;
    }

    message KeyControl {
      // If present, the key control must be communicated to the secure
      // environment prior to any usage. This message is automatically generated
      // by the Widevine License Server SDK.
      optional bytes key_control_block = 1;
      optional bytes iv = 2;
    }

    message OutputProtection {
      // Indicates whether HDCP is required on digital outputs, and which
      // version should be used.
      enum HDCP {
        HDCP_NONE = 0;
        HDCP_V1 = 1;
        HDCP_V2 = 2;
        HDCP_V2_1 = 3;
        HDCP_V2_2 = 4;
        HDCP_V2_3 = 5;
        HDCP_NO_DIGITAL_OUTPUT = 0xff;
      }
      optional HDCP hdcp = 1 [default = HDCP_NONE];

      // Indicate the CGMS setting to be inserted on analog output.
      enum CGMS {
        CGMS_NONE = 42;
        COPY_FREE = 0;
        COPY_ONCE = 2;
        COPY_NEVER = 3;
      }
      optional CGMS cgms_flags = 2 [default = CGMS_NONE];

      enum HdcpSrmRule {
        HDCP_SRM_RULE_NONE = 0;
        // In 'required_protection', this means most current SRM is required.
        // Update the SRM on the device. If update cannot happen,
        // do not allow the key.
        // In 'requested_protection', this means most current SRM is requested.
        // Update the SRM on the device. If update cannot happen,
        // allow use of the key anyway.
        CURRENT_SRM = 1;
      }
      optional HdcpSrmRule hdcp_srm_rule = 3 [default = HDCP_SRM_RULE_NONE];
      // Optional requirement to indicate analog output is not allowed.
      optional bool disable_analog_output = 4 [default = false];
      // Optional requirement to indicate digital output is not allowed.
      optional bool disable_digital_output = 5 [default = false];
    }

    message VideoResolutionConstraint {
      // Minimum and maximum video resolutions in the range (height x width).
      optional uint32 min_resolution_pixels = 1;
      optional uint32 max_resolution_pixels = 2;
      // Optional output protection requirements for this range. If not
      // specified, the OutputProtection in the KeyContainer applies.
      optional OutputProtection required_protection = 3;
    }

    message OperatorSessionKeyPermissions {
      // Permissions/key usage flags for operator service keys
      // (type = OPERATOR_SESSION).
      optional bool allow_encrypt = 1 [default = false];
      optional bool allow_decrypt = 2 [default = false];
      optional bool allow_sign = 3 [default = false];
      optional bool allow_signature_verify = 4 [default = false];
    }

    optional bytes id = 1;
    optional bytes iv = 2;
    optional bytes key = 3;
    optional KeyType type = 4;
    optional SecurityLevel level = 5 [default = SW_SECURE_CRYPTO];
    optional OutputProtection required_protection = 6;
    // NOTE: Use of requested_protection is not recommended as it is only
    // supported on a small number of platforms.
    optional OutputProtection requested_protection = 7;
    optional KeyControl key_control = 8;
    optional OperatorSessionKeyPermissions operator_session_key_permissions = 9;
    // Optional video resolution constraints. If the video resolution of the
    // content being decrypted/decoded falls within one of the specified ranges,
    // the optional required_protections may be applied. Otherwise an error will
    // be reported.
    // NOTE: Use of this feature is not recommended, as it is only supported on
    // a small number of platforms.
    repeated VideoResolutionConstraint video_resolution_constraints = 10;
    // Optional flag to indicate the key must only be used if the client
    // supports anti rollback of the user table.  Content provider can query the
    // client capabilities to determine if the client support this feature.
    optional bool anti_rollback_usage_table = 11 [default = false];
    // Optional not limited to commonly known track types such as SD, HD.
    // It can be some provider defined label to identify the track.
    optional string track_label = 12;
  }

  optional LicenseIdentification id = 1;
  optional Policy policy = 2;
  repeated KeyContainer key = 3;
  // Time of the request in seconds (UTC) as set in
  // LicenseRequest.request_time.  If this time is not set in the request,
  // the local time at the license service is used in this field.
  optional int64 license_start_time = 4;
  // TODO(b/65054419): Deprecate remote_attestation_verified in favor of
  // platform_verification_status, below.
  optional bool remote_attestation_verified = 5 [default = false];
  // Client token generated by the content provider. Optional.
  optional bytes provider_client_token = 6;
  // 4cc code specifying the CENC protection scheme as defined in the CENC 3.0
  // specification. Propagated from Widevine PSSH box. Optional.
  optional uint32 protection_scheme = 7;
  // 8 byte verification field "HDCPDATA" followed by unsigned 32 bit minimum
  // HDCP SRM version (whether the version is for HDCP1 SRM or HDCP2 SRM
  // depends on client max_hdcp_version).
  optional bytes srm_requirement = 8;
  // If present this contains a signed SRM file (either HDCP1 SRM or HDCP2 SRM
  // depending on client max_hdcp_version) that should be installed on the
  // client device.
  optional bytes srm_update = 9;
  // Indicates the status of any type of platform verification performed by the
  // server.
  optional PlatformVerificationStatus platform_verification_status = 10
      [default = PLATFORM_NO_VERIFICATION];
  // IDs of the groups for which keys are delivered in this license, if any.
  repeated bytes group_ids = 11;
}

enum ProtocolVersion {
  VERSION_2_0 = 20;
  VERSION_2_1 = 21;
  VERSION_2_2 = 22;
}

message LicenseRequest {
  message ContentIdentification {
    message WidevinePsshData {
      repeated bytes pssh_data = 1;
      optional LicenseType license_type = 2;
      optional bytes request_id = 3;  // Opaque, client-specified.
    }

    message WebmKeyId {
      optional bytes header = 1;
      optional LicenseType license_type = 2;
      optional bytes request_id = 3;  // Opaque, client-specified.
    }

    message ExistingLicense {
      optional LicenseIdentification license_id = 1;
      optional int64 seconds_since_started = 2;
      optional int64 seconds_since_last_played = 3;
      optional bytes session_usage_table_entry = 4;
    }

    message InitData {
      enum InitDataType {
        CENC = 1;
        WEBM = 2;
      }

      optional InitDataType init_data_type = 1 [default = CENC];
      optional bytes init_data = 2;
      optional LicenseType license_type = 3;
      optional bytes request_id = 4;
    }

    oneof content_id_variant {
      // Exactly one of these must be present.
      WidevinePsshData widevine_pssh_data = 1;
      WebmKeyId webm_key_id = 2;
      ExistingLicense existing_license = 3;
      InitData init_data = 4;
    }
  }

  enum RequestType {
    NEW = 1;
    RENEWAL = 2;
    RELEASE = 3;
  }

  // The client_id provides information authenticating the calling device.  It
  // contains the Widevine keybox token that was installed on the device at the
  // factory.  This field or encrypted_client_id below is required for a valid
  // license request, but both should never be present in the same request.
  optional ClientIdentification client_id = 1;
  optional ContentIdentification content_id = 2;
  optional RequestType type = 3;
  // Time of the request in seconds (UTC) as set by the client.
  optional int64 request_time = 4;
  // Old-style decimal-encoded string key control nonce.
  optional bytes key_control_nonce_deprecated = 5;
  optional ProtocolVersion protocol_version = 6 [default = VERSION_2_0];
  // New-style uint32 key control nonce, please use instead of
  // key_control_nonce_deprecated.
  optional uint32 key_control_nonce = 7;
  // Encrypted ClientIdentification message, used for privacy purposes.
  optional EncryptedClientIdentification encrypted_client_id = 8;
}

message LicenseError {
  enum Error {
    // The device credentials are invalid. The device must re-provision.
    INVALID_DRM_DEVICE_CERTIFICATE = 1;
    // The device credentials have been revoked. Re-provisioning is not
    // possible.
    REVOKED_DRM_DEVICE_CERTIFICATE = 2;
    // The service is currently unavailable due to the backend being down
    // or similar circumstances.
    SERVICE_UNAVAILABLE = 3;
  }
  optional Error error_code = 1;
}

message MetricData {
  enum MetricType {
    // The time spent in the 'stage', specified in microseconds.
    LATENCY = 1;
    // The UNIX epoch timestamp at which the 'stage' was first accessed in
    // microseconds.
    TIMESTAMP = 2;
  }

  message TypeValue {
    optional MetricType type = 1;
    // The value associated with 'type'.  For example if type == LATENCY, the
    // value would be the time in microseconds spent in this 'stage'.
    optional int64 value = 2 [default = 0];
  }

  // 'stage' that is currently processing the SignedMessage.  Required.
  optional string stage_name = 1;
  // metric and associated value.
  repeated TypeValue metric_data = 2;
}

message VersionInfo {
  // License SDK version reported by the Widevine License SDK. This field
  // is populated automatically by the SDK.
  optional string license_sdk_version = 1;
  // Version of the service hosting the license SDK. This field is optional.
  // It may be provided by the hosting service.
  optional string license_service_version = 2;
}

message SignedMessage {
  enum MessageType {
    LICENSE_REQUEST = 1;
    LICENSE = 2;
    ERROR_RESPONSE = 3;
    SERVICE_CERTIFICATE_REQUEST = 4;
    SERVICE_CERTIFICATE = 5;
    SUB_LICENSE = 6;
    CAS_LICENSE_REQUEST = 7;
    CAS_LICENSE = 8;
  }

  optional MessageType type = 1;
  optional bytes msg = 2;
  optional bytes signature = 3;
  optional bytes session_key = 4;
  // Remote attestation data which will be present in the initial license
  // request for ChromeOS client devices operating in verified mode. Remote
  // attestation challenge data is |msg| field above. Optional.
  optional RemoteAttestation remote_attestation = 5;

  repeated MetricData metric_data = 6;
  // Version information from the SDK and license service. This information is
  // provided in the license response.
  optional VersionInfo service_version_info = 7;
}