////////////////////////////////////////////////////////////////////////////////
// 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.
////////////////////////////////////////////////////////////////////////////////

// Data and Service definitions for Widevine DRM Service.

syntax = "proto2";

option java_package = "com.google.video.widevine.licensing";
import "protos/public/client_identification.proto";
import "protos/public/license_protocol.proto";
import "protos/public/license_server_sdk.proto";
package widevine;

// TODO(user): refactor license_services.proto and sdk_stats.proto.

enum ModularDrmType {
  WIDEVINE = 0;
  PLAYREADY = 1;
  FAIRPLAY = 2;
}

// LINT.IfChange
// The Modular DRM license request sent to the RPC service.
message ModularDrmLicenseRequest {
  // The request payload. This is usually the HTTP Post body of a request.
  // Required.
  optional bytes payload = 1;

  // A ContentKeySpec identifies a content key by track type name. It also
  // specifies the policy that should be used for this key.
  // LINT.IfChange
  message ContentKeySpec {
    // A track type is used to represent a set of tracks that share the same
    // content key and security level. Common values are SD, HD, UHD1, UHD2
    // and AUDIO. Content providers may use arbitrary strings for track type
    // as long as they are consistent with the track types used at registration
    // time. Required.
    optional string track_type = 1;

    // The following settings override pre-stored settings referenced by the
    // policy_name.
    // Security level defines the robustness requirements on key handling at
    // client side.
    optional License.KeyContainer.SecurityLevel security_level = 2;
    optional License.KeyContainer.OutputProtection required_output_protection =
        3;
    optional License.KeyContainer.OutputProtection requested_output_protection =
        4;
    // Optional content key Id for this track.  If specified, this Id is used to
    // identify the key for this track.  If not specified, the license server
    // will either generate or lookup the key Id for this track.
    optional bytes key_id = 5;
    // Optional content key for this track.  If specified, this key is used to
    // build the license.  If not specified, the license server will generate
    // or lookup the key for this track.
    optional bytes key = 6;

    // TODO (robinconnell): iv, key_type, and operator_session_key_permissions
    // where added to support OPERATION_SESSION licenses.  But with the addition
    // of the field the ContentKeySpec message is almost the same as the
    // License.KeyContainer message.  Merge the two messages needs to be
    // investigated.

    // Optional iv used to encrypt the keys.  If not specified random iv will be
    // generated.
    optional bytes iv = 7;
    optional License.KeyContainer.KeyType key_type = 8;
    optional License.KeyContainer.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.
    repeated License.KeyContainer.VideoResolutionConstraint
        video_resolution_constraints = 10;
  }

  // Specifies a list of content keys and policies to be included in a license.
  repeated ContentKeySpec content_key_specs = 2;

  // A shortcut for specifying which track types should be included in a
  // license.
  // This field is ignored if one or more content_key_specs is specified.
  // LINT.IfChange
  enum CommonTrackTypeSet {
    // Implies SD and HD.
    SD_HD = 0;
    // Implies SD only.
    SD_ONLY = 1;
    // Implies SD, HD, and UHD1.
    SD_UHD1 = 2;
    // Implies SD, HD, UHD1 and UHD2.
    SD_UHD2 = 3;
  }
  optional CommonTrackTypeSet allowed_track_types = 3 [default = SD_UHD1];

  // Identifier used to derive KeyId(s) and Content Key(s)
  // for each content_key_specs.track_type.  Required only
  // when the content id isn't part of the PSSH. Used for
  // backward-compatibility with existing YouTube CENC
  // videos. Ignored for assets whose PSSH includes a
  // content id.
  optional bytes content_id = 4;

  // Used to look up Content Key(s) and policy.  Required.
  optional string provider = 5;

  // A blob of data to be sent to client and bounce back in subsequent heartbeat
  // requests. Maps to license.license_id.prchase.id.
  optional string replay_data = 6;

  // License policy information could come from various sources. For any given
  // field in a policy, the final value is determined by (in the order by
  // highest precedence to lowest)
  // 1. request.policy  // acts as policy override.
  // 2. if !use_policy_overrides_exclusively,
  //      if request.has_policy_name
  //        GetStoredPolicy(request.policy_name)
  //      else
  //        GetStoredPolicy(GetRegisteredAsset(request.content_id).policy_name)

  // Policy overrides specified by a content provider proxy.
  optional License.Policy policy_overrides = 7;

  // Use a previously registered policy named <policy_name>.
  optional string policy_name = 8;

  // Use Policy attributes specified by policy_overrides and
  // skip any Policy lookup from storage.
  optional bool use_policy_overrides_exclusively = 9 [default = false];

  // Indicates whether this is a Widevine, PlayReady or FairPlay license
  // request.
  optional ModularDrmType drm_type = 10 [default = WIDEVINE];

  // This is now handled as a server configuration, only enabled for QA and UAT.
  optional bool allow_test_device_deprecated = 11 [deprecated = true];

  // The IP Address of the portal that is forwarding the license request from
  // the device.
  optional string client_ip_address = 13;

  // The client software identifier, as used by HTTP.
  optional string user_agent = 14;

  // Client token owned by Content Provider.  This value is added to the
  // license response.
  // TODO(user): Deprecated and use session_init instead.
  optional bytes provider_client_token = 15;

  // Session token owned by Content Provider.  This value is added to the
  // license response.
  // TODO(user): Deprecated and use session_init instead.
  optional bytes provider_session_token = 16;

  // Pass optional data to initial license.
  optional SessionInit session_init = 17;

  // Indicates whether to process the license request and return the parsed data
  // only, hence not generating an actual license.
  optional bool parse_only = 18 [default = false];

  // The request identifier for this license request as specified by the
  // content provider proxy.  Optional.
  optional string content_provider_request_id = 19 [default = "unspecified"];

  // Indicates all key and iv values in ContentKeySpec are encrypted with this
  // sesion key.  This session key is encrypted with the providers AES key. If
  // session_key is used, session_iv must also be specified.
  optional bytes session_key = 20;

  // Indicates all key and iv values in ContentKeySpec are encrypted with this
  // session IV.  This session IV is encrypted with the provider's AES key.
  optional bytes session_iv = 21;

  // In prod environment, normally license request from IN_TESTING devices
  // will be rejected. But if test_content is true, such request from
  // a IN_TESTING device will succeed.
  // In all other environments, test_content has no impact, licensing for
  // IN_TESTING wil be allowed regardless.
  // See b/26692995 for more info.
  optional bool test_content = 22 [default = false];

  // The name of the provider making the request.  This field will be
  // populated by content providers who are serving content packaged by
  // content owners.  If the content owner and content provider are the same,
  // this field will be empty.
  // Example: Play is a content provider which serves content packaged and
  // owned by the content owner, YouTube.
  optional string requesting_provider = 23;

  // Serialized ClientIdentification protobuf message returned by the Proxy SDK
  // GetClientInfoAsAtring() API.
  optional bytes client_id_msg = 24;

  // If set to true and the device is L3, return AUDIO and SD keys only.
  // This takes precedence over allowed_track_types.
  optional bool sd_only_for_l3 = 25 [default = false];

  // Content providers who host their own service certificate must set this
  // field by using the ProxySDK(internally, RequestInspector) API.
  optional PlatformVerificationStatus platform_verification_status = 26
      [default = PLATFORM_NO_VERIFICATION];
}


// LINT.IfChange
// A generic protobuf used as the request format of various Modular DRM APIs,
// including GetModularDrmLicense and KeyRequest APIs.
// The following docs describe how the proto is interpreted by various APIs.
message SignedModularDrmRequest {
  // For GetModularDrmLicenseExternal, request is a ModularDrmLicenseRequest in
  // JSON format.
  optional bytes request = 1;
  optional bytes signature = 2;
  // Identifies the entity sending / signing the request.
  optional string signer = 3;
  // The IP Address of the portal that is forwarding the request from the
  // original sender.
  optional string client_ip_address = 4;
  // The client software identifier, as used by HTTP.
  optional string user_agent = 5;
  // The request identifier for this license request as specified by the
  // content provider proxy.  Optional.
  optional string content_provider_request_id = 6 [default = "unspecified"];
  // The provider on behalf of whom, this request is made.  This field will be
  // populated by content providers who are serving content packaged by content
  // owners ("signer").
  optional string provider = 7;
}

// LINT.IfChange
message SignedModularDrmResponse {
  // A CommonEncryptionResponse message in JSON format.
  optional bytes response = 1;
  optional bytes signature = 2;
}


message LicenseMetadata {
  // DRM-specific status code from the WvmStatus enum. It's a uint32 here
  // because providers can use the 'setstatus' field to supply their own
  // arbitrary return values.
  optional uint32 drm_status_code = 1;
  // Asset Identifier that was generated by this DRM service.
  optional uint64 asset_id = 2;
  optional string asset_name = 4;
}


// LINT.IfChange
message ModularDrmLicenseResponse {
  enum Status {
    OK = 0;
    SIGNATURE_FAILED = 1;
    INVALID_LICENSE_CHALLENGE = 2;
    INVALID_CONTENT_INFO = 3;
    POLICY_UNKNOWN = 4;
    MALFORMED_REQUEST = 5;
    INTERNAL_ERROR = 6;
    PROVIDER_MISSING = 7;
    INVALID_REQUEST = 8;
    ACCESS_DENIED = 9;
    SIGNING_KEY_EXPIRED = 10;
  }
  optional Status status = 1;
  optional string status_message = 2;
  optional bytes license = 3;
  message LicenseMetadata {
    optional bytes content_id = 1;
    optional LicenseType license_type = 2;
    optional LicenseRequest.RequestType request_type = 3;
    // The current SRM version sent back to client in the license.
    optional uint32 srm_version = 4;
    // Whether SRM file was included in the license.
    optional bool srm_included = 5 [default = false];
    // Sets the value from
    // ClientIdentification.ClientCapabilities.can_update_srm in the license
    // request.
    optional bool can_update_srm = 6 [default = false];
    // SessionInit that was used when generating the license.
    optional SessionInit session_init = 7;
  }
  optional LicenseMetadata license_metadata = 4;
  message Track {
    optional string type = 1;
    optional bytes key_id = 2;
  }
  // A subset of data from the Widevine PSSH.
  message Pssh {
    repeated bytes key_id = 1;
    optional bytes content_id = 2;
  }
  // List of tracks for which keys exist in the license response.
  repeated Track supported_tracks = 5;
  // Make as identified from the provisioned device info.  If that is not
  // available, the device make will be retrieved from the license request.
  optional string make = 6;
  // Model as identified from the provisioned device info.  If that is not
  // available, the device model will be retrieved from the license request.
  optional string model = 7;
  // Set to true if the license request contained remote attestation challenge
  // and the challenge was verified.
  optional bool remote_attestation_verified = 8;
  // Widevine-defined security level.
  optional uint32 security_level = 9;
  // Actual SDK license status as defined in widevine/server/sdk/error.proto.
  optional uint32 internal_status = 10;
  // Usage report sent in a license release.
  optional SessionUsage session_usage = 11;
  optional SessionState session_state = 12;
  // Globally unique serial number of certificate associated with this
  // device.
  optional bytes drm_cert_serial_number = 13;
  // Whether the device (make/model) making the license request is whitelisted.
  // Indicates the type of message in the license response.
  optional SignedMessage.MessageType message_type = 15;
  // Optional Android Id reported by the Android client.
  // See go/avi-unique-device-id
  optional bytes android_id = 16;
  // If this is a group key license, this is the group identifier from the PSSH.
  optional bytes group_id = 17;
  // Platform specifies the OS or device type and perhaps other software
  // information for the device receving this license response.
  // Example: Android, iOS, Chrome, PC.
  optional string platform = 18;
  optional Pssh pssh_data = 20;
  // Maximum HDCP version specified by the client.
  optional ClientIdentification.ClientCapabilities.HdcpVersion
      client_max_hdcp_version = 21;
  // Optional client information name/value pairs from the client.
  repeated ClientIdentification.NameValue client_info = 22;
  // Optional number of seconds before a signing key expires.
  optional int64 signature_expiration_secs = 23;
  // Set to true, if license request was for "live" stream.
  optional bool is_live = 24 [default = false];
  // Platform verification status
  optional PlatformVerificationStatus platform_verification_status = 25
    [default = PLATFORM_UNVERIFIED];
  // The "provider" field in ModularDrmLicenseRequest.
  optional string content_owner = 26;
  // The "requesting_provider" in ModularDrmLicenseRequest.  If
  // "requesting_provider" is empty, then "provider" from
  // ModularDrmLicenseRequest will be set here.
  optional string content_provider = 27;
  // SystemID of the requesting device.
  optional uint32 system_id = 28;
}

message LicenseResponse {
  // Each license is a Base64-encoded string which is of the format
  // <status><asset_id><license blob>.  Multiple licenses are separated by a
  // comma.  Required.
  optional string licenses = 2;
  // License for the requested asset.  This should not be returned to the
  // client, but possibly evaluated by the provider.  The number of
  // license_metadata fields must be the same as the number of licenses.
  // Required.
  repeated LicenseMetadata license_metadata = 3;
  // Make as specified in the license request.
  optional string make = 4;
  // Model as specified in the license request.
  optional string model = 5;
  // Platform specifies the OS or device type and perhaps other software
  // information for the device receving this license response.
  // Example: Android, iOS, Chrome, PC.
  optional string platform = 6;
}