// Copyright 2018 Google LLC. All Rights Reserved. This file and proprietary // source code may only be used and distributed under the Widevine Master // License Agreement. // Description: // Definitions of the protocol buffer messages used in the Widevine license // exchange protocol. syntax = "proto2"; package video_widevine; // need this if we are using libprotobuf-cpp-2.3.0-lite option optimize_for = LITE_RUNTIME; option java_package = "com.google.video.widevine.protos"; enum LicenseType { STREAMING = 1; OFFLINE = 2; // License type decision is left to the provider. AUTOMATIC = 3; } 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; } // This message is used to indicate the license cateogry spec for a license as // a part of initial license issuance. message LicenseCategorySpec { // Possible license categories. enum LicenseCategory { // By default, License is used for single content. SINGLE_CONTENT_LICENSE_DEFAULT = 0; // License is used for multiple contents (could be a combination of // single contents and groups of contents). MULTI_CONTENT_LICENSE = 1; // License is used for contents logically grouped. GROUP_LICENSE = 2; } // Optional. License category indicates if license is used for single // content, multiple contents (could be a combination of // single contents and groups of contents) or a group of contents. optional LicenseCategory license_category = 1; // Optional. Content or group ID covered by the license. oneof content_or_group_id { // Content_id would be present if it is a license for single content. bytes content_id = 2; // Group_id would be present if the license is a multi_content_license or // group_license. Group Id could be the name of a group of contents, // defined by licensor. bytes group_id = 3; } } message License { 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]; // Enables "soft enforcement" of rental_duration_seconds. Initial playback // must always start before rental duration expires. In order to allow // subsequent playbacks to start after the rental duration expires, // soft_enforce_playback_duration must be true. Otherwise, subsequent // playbacks will not be allowed once rental duration expires. Optional. optional bool soft_enforce_rental_duration = 15 [default = true]; } message KeyContainer { enum KeyType { // Exactly one key of this type must appear. SIGNING = 1; CONTENT = 2; KEY_CONTROL = 3; OPERATOR_SESSION = 4; ENTITLEMENT = 5; } // 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 { // |key_control| is documented in: // Widevine Modular DRM Security Integration Guide for CENC // 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]; } 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]; } // KeyCategorySpec message is used to identify if current key is generated // for a single content or a group of contents. message KeyCategorySpec { // Represents what kind of content a key is used for. enum KeyCategory { // By default, key is created for single content. SINGLE_CONTENT_KEY_DEFAULT = 0; // Key is created for a group of contents. GROUP_KEY = 1; } // Indicate if the current key is created for single content or for group // use. optional KeyCategory key_category = 1; // Id for key category. If it is a key for single content, this id // represents the content_id. Otherwise, it represents a group_id. oneof content_or_group_id { bytes content_id = 2; bytes group_id = 3; } } 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; // A Key Category Spec is used to identify if current key is generated for a // single content or a group of contents. optional KeyCategorySpec key_category_spec = 13; } 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). // Additional details can be found in Widevine Modular DRM Security // Integration Guide for CENC. 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; // Optional. LicenseCategorySpec is used to indicate the license category for // a license. It could be used as a part of initial license issuance or shown // as a part of license in license response. optional LicenseCategorySpec license_category_spec = 12; } enum ProtocolVersion { VERSION_2_0 = 20; VERSION_2_1 = 21; } message LicenseRequest { message ContentIdentification { message CencDeprecated { repeated bytes pssh = 1; optional LicenseType license_type = 2; optional bytes request_id = 3; // Opaque, client-specified. } message WebmDeprecated { 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. optional CencDeprecated cenc_id_deprecated = 1; optional WebmDeprecated webm_id_deprecated = 2; optional ExistingLicense existing_license = 3; optional InitData init_data = 4; //} } message SubSessionData { // Required. The key ID for the corresponding SUB_SESSION_KEY. The // value must match the sub_session_key_id field for a // corresponding SubLicense message from the PSSH. optional string sub_session_key_id = 1; // Required. The nonce for the track. optional uint32 nonce = 2; // Required for initial license request used for each CONTENT key_container // to know which nonce to use for building its key control block. // Not needed for renewal license request. optional string track_label = 3; } 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; // Optional sub session context information. Required for using // SubLicenses from the PSSH. repeated SubSessionData sub_session_data = 9; } 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 RemoteAttestation { // Encrypted ClientIdentification message containing the device remote // attestation certificate. Required. optional EncryptedClientIdentification certificate = 1; // Bytes of salt which were added to the remote attestation challenge prior to // signing it. Required. optional bytes salt = 2; // Signed remote attestation challenge + salt. Required. optional bytes signature = 3; } 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; } enum HashAlgorithmProto { // Unspecified hash algorithm: SHA_256 shall be used for ECC based algorithms // and SHA_1 shall be used otherwise. HASH_ALGORITHM_UNSPECIFIED = 0; HASH_ALGORITHM_SHA_1 = 1; HASH_ALGORITHM_SHA_256 = 2; HASH_ALGORITHM_SHA_384 = 3; } 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; EXTERNAL_LICENSE_REQUEST = 9; EXTERNAL_LICENSE = 10; } enum SessionKeyType { UNDEFINED = 0; WRAPPED_AES_KEY = 1; EPHEMERAL_ECC_PUBLIC_KEY = 2; } optional MessageType type = 1; optional bytes msg = 2; // Required field that contains the signature of the bytes of msg. // For license requests, the signing algorithm is determined by the // certificate contained in the request. // For license responses, the signing algorithm is HMAC with signing key based // on |session_key|. optional bytes signature = 3; // If populated, the contents of this field will be signaled by the // |session_key_type| type. If the |session_key_type| is WRAPPED_AES_KEY the // key is the bytes of an encrypted AES key. If the |session_key_type| is // EPHEMERAL_ECC_PUBLIC_KEY the field contains the bytes of an RFC5208 ASN1 // serialized ECC public key. 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; // Optional field that contains the algorithm type used to generate the // session_key and signature in a LICENSE message. optional SessionKeyType session_key_type = 8 [default = WRAPPED_AES_KEY]; // The core message is the simple serialization of fields used by OEMCrypto. // This field was introduced in OEMCrypto API v16. optional bytes oemcrypto_core_message = 9; // Optional field that indicates the hash algorithm used in signature scheme. optional HashAlgorithmProto hash_algorithm = 10; // If true it indicates that a LICENSE message session key was based on an // alternate key provided by the client credentials. optional bool using_secondary_key = 11; } message GroupKeys { enum GroupLicenseVersion { GROUP_LICENSE_VERSION_1 = 0; GROUP_LICENSE_VERSION_2 = 1; } message GroupKeyData { // Required track type. This indicates the track type to which this key // belongs. optional string track_type = 1; // A required signed message. The message body contains a serialized group // msg. optional bytes key = 2; } // Optional key container array used in group licensing V1. This is not used // in V2. repeated License.KeyContainer key = 1 [deprecated = true]; // Byte string that identifies the group to which this license material // belongs. optional bytes group_id = 2; // Required version id beginning with version 2. If not present version 1 // should be assumed. optional GroupLicenseVersion version = 3 [default = GROUP_LICENSE_VERSION_1]; // Optional key container array for group licensing V2. repeated GroupKeyData key_data = 4; } // ---------------------------------------------------------------------------- // certificate_provisioning.proto // ---------------------------------------------------------------------------- // Description of section: // Public protocol buffer definitions for Widevine Device Certificate // Provisioning protocol. // A KeyToCertify contains a client generated public key to be incorporated into // a signed certificate. message PublicKeyToCertify { // A KeyType indicates a high level key type. enum KeyType { KEY_TYPE_UNSPECIFIED = 0; RSA = 1; ECC = 2; } // |public_key| contains the bytes of an ASN.1 DER-encoded // SubjectPublicKeyInfo as specified in RFC 5280. optional bytes public_key = 1; // KeyType contains a highlevel hint to use in parsing the serialized key // contained in |public_key|. If the key is an EC key, curve parameters can be // extracted from the deserialized key. // Keys are expected to match the certificate key type in the device record. optional KeyType key_type = 2; // The signature of |public_key|. // Keys that are signed using ECDSA or RSA should hash the message using // SHA-256. optional bytes signature = 3; } // ProvisioningOptions specifies the type of certificate to specify and // in the case of X509 certificates, the certificate authority to use. message ProvisioningOptions { enum CertificateType { WIDEVINE_DRM = 0; // Default. The original certificate type. X509 = 1; // X.509 certificate. WIDEVINE_KEYBOX = 2; } optional CertificateType certificate_type = 1 [default = WIDEVINE_DRM]; // Contains the application-specific name used to identify the certificate // authority for signing the generated certificate. This is required if the // certificate type is X509. optional string certificate_authority = 2; // System ID for OTA keybox provisioning. Requires device secure boot. optional uint32 system_id = 3; } // Provisioning request sent by client devices to provisioning service. message ProvisioningRequest { message EncryptedSessionKeys { message SessionKeys { // 16 bytes encryption key generated by client, used by the server to: // (1) AES-128-CBC decrypt encrypted_client_id in // EncryptedClientIdentification which is in RemoteAttestation // (2) AES-128-CBC encrypt device_key to be returned in // ProvisioningResponse. optional bytes encryption_key = 1; // 32 bytes mac key generated by client, used by server to sign // the ProvisioningResponse. optional bytes mac_key = 2; } // Serial number of certificate which was used to encrypt the session keys. // Required. optional bytes certificate_serial_number = 1; // Serialized, encrypted session keys. Required. optional bytes encrypted_session_keys = 2; } oneof clear_or_encrypted_client_id { // Device root of trust and other client identification. Required. ClientIdentification client_id = 1; EncryptedClientIdentification encrypted_client_id = 5; } // Nonce value used to prevent replay attacks. Required. optional bytes nonce = 2; // Options for type of certificate to generate. Optional. optional ProvisioningOptions options = 3; oneof spoid_param { // Stable identifier, unique for each device + application (or origin). // To be deprecated. bytes stable_id = 4; // Service provider ID from the service certificate's provider_id field. // Preferred parameter. bytes provider_id = 6; // Client-generated stable per-origin identifier to be copied directly // to the client certificate serial number. bytes spoid = 7; } // SessionKeys encrypted using a service cert public key. // Required for keybox provisioning. optional EncryptedSessionKeys encrypted_session_keys = 8; // Specifies the public key that should be certified by the provisioning // server. The client holds the private key. If specified, the response no // longer needs to contain server generated |device_rsa_key|. optional PublicKeyToCertify certificate_public_key = 10; } // Provisioning response sent by the provisioning server to client devices. // This message is used for both regular Widevine DRM certificates and for // application-specific X.509 certificates. message ProvisioningResponse { message OtaKeybox { // Iv used along with SessionKeys.encryption_key for encrypting device key. optional bytes device_key_encryption_iv = 1; // Device key component of the keybox, encrypted using the // SessionKeys.encryption_key in the request and |device_key_encryption_iv| // above. optional bytes encrypted_device_key = 2; // Device CA token component of the keybox. optional bytes device_ca_token = 3; } // AES-128 encrypted device private RSA key. PKCS#1 ASN.1 DER-encoded. // Required. For X.509 certificates, the private RSA key may also include // a prefix as specified by private_key_prefix in the X509CertificateMetadata // proto message. optional bytes device_rsa_key = 1; // Initialization vector used to encrypt device_rsa_key. Required. optional bytes device_rsa_key_iv = 2; // For Widevine DRM certificates, this contains the serialized // SignedDrmCertificate. For X.509 certificates, this contains the PEM // encoded X.509 certificate. Required. optional bytes device_certificate = 3; // Nonce value matching nonce in ProvisioningRequest. Required. optional bytes nonce = 4; // Key used to wrap device_rsa_key when DRM provisioning an OEM factory // provisioned device. Encrypted with the device OEM public key using // RSA-OAEP. optional bytes wrapping_key = 5; // Only populated in OTA keybox provisioning response. optional OtaKeybox ota_keybox = 6; } // Protocol-specific context data used to hold the state of the server in // stateful provisioning protocols. For more information, please refer to // "Widevine DRM Provisioning using Third-Part and Stateful Protocols". message ProvisioningContext { // Serialized ProvisioningContextKeyData. Required. optional bytes key_data = 1; // Protocol-dependent context data, encrypted with key and IV in key_data. // Required. optional bytes context_data = 2; } message SignedProvisioningContext { // ProvisioningContext in bytes. optional bytes provisioning_context = 1; // RSASSA-PSS signature of provisioning_context. Signed with service private // key. optional bytes signature = 2; } // Cryptographic tokens to be used for ProvisioningContext. message ProvisioningContextKeyData { // Encryption key, usually 32 bytes used for AES-256-CBC. Required. optional bytes encryption_key = 1; // Encryption IV, 16 bytes. Required. optional bytes encryption_iv = 2; } // Serialized ProvisioningRequest or ProvisioningResponse signed with // The message authentication key. message SignedProvisioningMessage { enum ProtocolVersion { SERVICE_CERTIFICATE_REQUEST = 1; // Service certificate request. PROVISIONING_20 = 2; // Keybox factory-provisioned devices. PROVISIONING_30 = 3; // OEM certificate factory-provisioned devices. ARCPP_PROVISIONING = 4; // ChromeOS/Arc++ devices. // Devices use Boot Certificate Chain (BCC) to provision an OEM certificate. PROVISIONING_40 = 5; INTEL_SIGMA_101 = 101; // Intel Sigma 1.0.1 protocol. } // Serialized protobuf message for the corresponding protocol and stage of // the provisioning exchange. ProvisioningRequest or ProvisioningResponse // in the case of Provisioning 2.0, 3.0 and ARCPP_PROVISIONING. Required. optional bytes message = 1; // HMAC-SHA256 (Keybox) or RSASSA-PSS (OEM) signature of message. Required // for provisioning 2.0 and 3.0. For ARCPP_PROVISIONING, only used in // response. optional bytes signature = 2; // Version number of provisioning protocol. optional ProtocolVersion protocol_version = 3 [default = PROVISIONING_20]; // Protocol-specific context / state information for multiple-exchange, // stateful provisioing protocols. Optional. optional SignedProvisioningContext signed_provisioning_context = 4; // Remote attestation data to authenticate that the ChromeOS client device // is operating in verified mode. Remote attestation challenge data is // |message| field above. Required for ARCPP_PROVISIONING request. // It contains signature of |message|. optional RemoteAttestation remote_attestation = 5; // The core message is the simple serialization of fields used by OEMCrypto. // This field was introduced in OEMCrypto API v16. The core message format is // documented in the "Widevine Core Message Serialization". optional bytes oemcrypto_core_message = 6; // Optional field that indicates the hash algorithm used in signature scheme. optional HashAlgorithmProto hash_algorithm = 7; } // ---------------------------------------------------------------------------- // client_identification.proto // ---------------------------------------------------------------------------- // Description: // ClientIdentification messages used by provisioning and license protocols. // ClientIdentification message used to authenticate the client device. message ClientIdentification { enum TokenType { KEYBOX = 0; DRM_DEVICE_CERTIFICATE = 1; REMOTE_ATTESTATION_CERTIFICATE = 2; OEM_DEVICE_CERTIFICATE = 3; BOOT_CERTIFICATE_CHAIN = 4; } message NameValue { optional string name = 1; optional string value = 2; } // Capabilities which not all clients may support. Used for the license // exchange protocol only. message ClientCapabilities { enum HdcpVersion { 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; } enum CertificateKeyType { RSA_2048 = 0; RSA_3072 = 1; } enum AnalogOutputCapabilities { ANALOG_OUTPUT_UNKNOWN = 0; ANALOG_OUTPUT_NONE = 1; ANALOG_OUTPUT_SUPPORTED = 2; ANALOG_OUTPUT_SUPPORTS_CGMS_A = 3; } optional bool client_token = 1 [default = false]; optional bool session_token = 2 [default = false]; optional bool video_resolution_constraints = 3 [default = false]; optional HdcpVersion max_hdcp_version = 4 [default = HDCP_NONE]; optional uint32 oem_crypto_api_version = 5; // Client has hardware support for protecting the usage table, such as // storing the generation number in secure memory. For Details, see: // Widevine Modular DRM Security Integration Guide for CENC optional bool anti_rollback_usage_table = 6 [default = false]; // The client shall report |srm_version| if available. optional uint32 srm_version = 7; // A device may have SRM data, and report a version, but may not be capable // of updating SRM data. optional bool can_update_srm = 8 [default = false]; repeated CertificateKeyType supported_certificate_key_type = 9; optional AnalogOutputCapabilities analog_output_capabilities = 10 [default = ANALOG_OUTPUT_UNKNOWN]; optional bool can_disable_analog_output = 11 [default = false]; } message ClientCredentials { // Deprecated. Use credential_type instead. optional TokenType type = 1 [default = KEYBOX]; optional bytes token = 2; // Additional types of credentials that may be present in the client // identification. enum CredentialType { CREDENTIAL_TYPE_UNKNOWN = 0; // CBOR format used by the Provisioning 4.0 phase 3 uploading model. CREDENTIAL_TYPE_BCC_SIGNATURE_CBOR = 1; // PKCS7 format, used by Provisioning 4.0 signing model. CREDENTIAL_TYPE_BCC_SIGNATURE_PKCS7 = 2; } // The type of the token. optional CredentialType credential_type = 3; } // Type of factory-provisioned device root of trust. Optional. optional TokenType type = 1 [default = KEYBOX]; // Factory-provisioned device root of trust. Required. optional bytes token = 2; // Optional client information name/value pairs. repeated NameValue client_info = 3; // Client token generated by the content provider. Optional. optional bytes provider_client_token = 4; // Number of licenses received by the client to which the token above belongs. // Only present if client_token is specified. optional uint32 license_counter = 5; // List of non-baseline client capabilities. optional ClientCapabilities client_capabilities = 6; // Serialized VmpData message. Optional. optional bytes vmp_data = 7; // Optional field that may contain additional provisioning credentials. optional ClientCredentials device_credentials = 8; } // EncryptedClientIdentification message used to hold ClientIdentification // messages encrypted for privacy purposes. message EncryptedClientIdentification { // Provider ID for which the ClientIdentifcation is encrypted (owner of // service certificate). optional string provider_id = 1; // Serial number for the service certificate for which ClientIdentification is // encrypted. optional bytes service_certificate_serial_number = 2; // Serialized ClientIdentification message, encrypted with the privacy key // using AES-128-CBC with PKCS#5 padding. optional bytes encrypted_client_id = 3; // Initialization vector needed to decrypt encrypted_client_id. optional bytes encrypted_client_id_iv = 4; // AES-128 privacy key, encrypted with the service public key using RSA-OAEP. optional bytes encrypted_privacy_key = 5; } // ---------------------------------------------------------------------------- // device_certificate.proto // ---------------------------------------------------------------------------- // Description: // Device certificate and certificate status list format definitions. // DRM certificate definition for user devices, intermediate, service, and root // certificates. message DrmDeviceCertificate { enum CertificateType { ROOT = 0; DRM_INTERMEDIATE = 1; DRM_USER_DEVICE = 2; SERVICE = 3; PROVISIONER = 4; } // Type of certificate. Required. optional CertificateType type = 1; // 128-bit globally unique serial number of certificate. // Value is 0 for root certificate. Required. optional bytes serial_number = 2; // POSIX time, in seconds, when the certificate was created. Required. optional uint32 creation_time_seconds = 3; // Device public key. PKCS#1 ASN.1 DER-encoded. Required. optional bytes public_key = 4; // Widevine system ID for the device. Required for intermediate and // user device certificates. optional uint32 system_id = 5; // Deprecated field, which used to indicate whether the device was a test // (non-production) device. The test_device field in ProvisionedDeviceInfo // below should be observed instead. optional bool test_device_deprecated = 6 [deprecated = true]; // Service identifier (web origin) for the provider which owns the // certificate. Required for service and provisioner certificates. optional string provider_id = 7; } // Contains DRM and OEM certificate status and device information for a // specific system ID. message DeviceCertificateStatus { enum Status { VALID = 0; REVOKED = 1; }; // Serial number of the intermediate DrmDeviceCertificate to which this // message refers. Required. optional bytes drm_serial_number = 1; // Status of the certificate. Optional. optional Status status = 2 [default = VALID]; // Device model information about the device to which the intermediate // certificate(s) correspond. optional ProvisionedDeviceInfo device_info = 4; // Serial number of the OEM X.509 intermediate certificate for this type // of device. Present only if the device is OEM-provisioned. optional bytes oem_serial_number = 5; } // List of DeviceCertificateStatus. Used to propagate certificate revocation // status and device information. message DeviceCertificateStatusList { // POSIX time, in seconds, when the list was created. Required. optional uint32 creation_time_seconds = 1; // DeviceCertificateStatus for each system ID. repeated DeviceCertificateStatus certificate_status = 2; } // Signed CertificateStatusList message SignedCertificateStatusList { // Serialized DeviceCertificateStatusList. Required. optional bytes certificate_status_list = 1; // Signature of certificate_status_list. Signed with root certificate private // key using RSASSA-PSS. Required. optional bytes signature = 2; } // ---------------------------------------------------------------------------- // provisioned_device_info.proto // ---------------------------------------------------------------------------- // Description: // Provisioned device info format definitions. // Contains device model information for a provisioned device. message ProvisionedDeviceInfo { enum WvSecurityLevel { // Defined in "Widevine Security Integration Guide for DASH on Android" LEVEL_UNSPECIFIED = 0; LEVEL_1 = 1; LEVEL_2 = 2; LEVEL_3 = 3; } // Widevine system ID for the device. Mandatory. optional uint32 system_id = 1; // Name of system-on-a-chip. Optional. optional string soc = 2; // Name of manufacturer. Optional. optional string manufacturer = 3; // Manufacturer's model name. Matches "brand" in device metadata. Optional. optional string model = 4; // Type of device (Phone, Tablet, TV, etc). optional string device_type = 5; // Device model year. Optional. optional uint32 model_year = 6; // Widevine-defined security level. Optional. optional WvSecurityLevel security_level = 7 [default = LEVEL_UNSPECIFIED]; // True if the certificate corresponds to a test (non production) device. // Optional. optional bool test_device = 8 [default = false]; } // ---------------------------------------------------------------------------- // widevine_pssh.proto // ---------------------------------------------------------------------------- // Description: // Public protocol buffer definitions for Widevine Cenc Header // protocol. // Each SubLicense message represents a single content key. These keys can be // added to Widevine CENC initialization data to support both content grouping // and key rotation. message SubLicense { // Required. The key_id of a SUB_SESSION_KEY received in the master license. // SUB_SESSION_KEY is defined in the Widevine License Protocol. optional string sub_session_key_id = 1; // Required. The key_msg contains the bytes of a serialized SignedMessage // proto. Internally the message field will contain a serialized KeyContainer // holding a single content key. optional bytes key_msg = 2; // TODO(jfore): There is some uncertainty about including the current group in // a license. This may change. // Byte string that identifies the group to which this this content // belongs. optional bytes group_id = 13; } 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; } // Entitlement or content key IDs. Can only 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; // Video feature identifier, which is used in conjunction with |content_id| // to determine the set of keys to be returned in the license. Cannot be // present in conjunction with |key_ids|. // Current values are "HDR". optional string video_feature = 15; // Audiofeature identifier, which is used in conjunction with |content_id| // to determine the set of keys to be returned in the license. Cannot be // present in conjunction with |key_ids|. // Current values are "commentary". optional string audio_feature = 16; // Entitlement period index for media using entitlement key rotation. Can only // present in ENTITLEMENT PSSHs. It always corresponds to the entitlement key // period. optional uint32 entitlement_period_index = 17; //////////////////////////// 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]; } // Signed device certificate definition. // DrmDeviceCertificate signed by a higher (CA) DRM certificate. message SignedDrmDeviceCertificate { // Serialized certificate. Required. optional bytes drm_certificate = 1; // Signature of certificate. Signed with root or intermediate // certificate specified below. Required. optional bytes signature = 2; // SignedDrmDeviceCertificate used to sign this certificate. optional SignedDrmDeviceCertificate signer = 3; } // This message is used by the server to preserve and restore session state. message SessionState { optional LicenseIdentification license_id = 1; optional bytes signing_key = 2; optional uint32 keybox_system_id = 3; // Provider client token sent back in the license. optional bytes provider_client_token = 4; // License counter associated with the avove token. optional uint32 license_counter = 5; } message CASDrmLicenseRequest { // The request payload. This is usually the HTTP Post body of a request. // Required. optional bytes payload = 1; // The content provider whose proxy is sending this license request onto the // Widevine license service. Required. optional string provider_id = 2; // An identifier supplied by a content provider, used to identify a piece of // content and derive key IDs and content keys. optional bytes content_id = 3; // A ContentKeySpec identifies a content key by track type name. It also // specifies the policy that should be used for this key. // TODO(hali): Consolidate this ContentKeySpec with // ModularDrmLicenseRequest_ContentKeySpec. Both should include a common // ContentKeySpec. message ContentKeySpec { optional License.KeyContainer.SecurityLevel security_level = 1; optional License.KeyContainer.OutputProtection required_output_protection = 2; optional License.KeyContainer.OutputProtection requested_output_protection = 3; // Optionally specify even, odd or single slot for key rotation. repeated CASEncryptionResponse.KeyInfo entitlement_keys = 4; optional License.KeyContainer.KeyType key_type = 5; // 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 packaging // time. optional string track_type = 6; // A Key Category Spec is used to identify if current key is generated for a // single content or a group of contents. optional License.KeyContainer.KeyCategorySpec key_category_spec = 7; } repeated ContentKeySpec content_key_specs = 4; // Policy for the entire license such as playback duration. optional License.Policy policy = 5; } message CASEncryptionRequest { optional bytes content_id = 1; optional string provider = 2; // Optional track types such as "AUDIO", SD" or "HD". repeated string track_types = 3; // Indicates if the client is using key rotation. If true, the server will // return one key for EVEN and one key for ODD, otherwise only a single key is // returned. optional bool key_rotation = 4; // Optional value which can be used to indicate a group. // If present the CasEncryptionResponse will return key based on the group // id. optional bytes group_id = 5; } message CASEncryptionResponse { enum Status { UNKNOWN = 0; OK = 1; SIGNATURE_FAILED = 2; ACCESS_DENIED = 3; INTERNAL_ERROR = 4; INVALID_ARGUMENT = 5; PROVIDER_ID_MISSING = 6; CONTENT_ID_MISSING = 7; TRACK_TYPE_MISSING = 8; } message KeyInfo { enum KeySlot { UNKNOWN = 0; SINGLE = 1; EVEN = 2; ODD = 3; }; optional bytes key_id = 1; optional bytes key = 2; // Optional label used for the key. optional string track_type = 3; optional KeySlot key_slot = 4; } optional Status status = 1; optional string status_message = 2; optional bytes content_id = 3; repeated KeyInfo entitlement_keys = 4; // If keys shown in the encryption response are for group usage, this is the // group identifier. optional bytes group_id = 5; } message SignedCASEncryptionRequest { optional bytes request = 1; optional bytes signature = 2; // Identifies the entity sending / signing the request. optional string signer = 3; } message SignedCASEncryptionResponse { // Serialized CASEncryptionResponse message. optional bytes response = 1; optional bytes signature = 2; } message CASDrmLicenseResponse { enum Status { UNKNOWN = 0; OK = 1; SIGNATURE_FAILED = 2; INVALID_LICENSE_CHALLENGE = 3; PROVIDER_ID_MISSING = 4; INVALID_CONTENT_INFO = 5; EMPTY_CONTENT_INFO = 6; CONTENT_ID_MISMATCH = 7; MISSING_CONTENT_ID = 8; MALFORMED_REQUEST = 9; } optional Status status = 1; optional string status_message = 2; // Serialzed bytes for a CAS license. // TODO(hali): Until a CAS license protocol is defined, this field is a // serialized License message defined in license_protocol.proto. optional bytes license = 3; // Actual SDK license status as defined in widevine/server/sdk/error.proto. optional uint32 internal_status = 4; // Indicates the type of message in the license response. optional SignedMessage.MessageType message_type = 5; // A subset of data from the Widevine PSSH. message PsshData { repeated bytes key_id = 1; optional bytes content_id = 2; } optional PsshData pssh_data = 6; optional SessionState session_state = 7; optional string content_owner = 8; optional string content_provider = 9; } message SignedCASDrmRequest { optional bytes request = 1; optional bytes signature = 2; // Identifies the entity sending / signing the request. Required if signature // is present. 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; optional string provider = 6; } message SignedCASDrmResponse { optional bytes response = 1; optional bytes signature = 2; } // ---------------------------------------------------------------------------- // drm_certificate.proto // ---------------------------------------------------------------------------- // Description of section: // Definition of the root of trust identifier proto. The proto message contains // the EC-IES encrypted identifier (e.g. keybox unique id) for a device and // an associated hash. These can be used by Widevine to identify the root of // trust that was used to acquire a DRM certificate. // // In addition to the encrypted part and the hash, the proto contains the // version of the root of trust id which implies the EC key algorithm that was // used. // Next id: 5 message RootOfTrustId { // The version specifies the EC algorithm that was used to generate the // root of trust id. enum RootOfTrustIdVersion { // Should not be used. ROOT_OF_TRUST_ID_VERSION_UNSPECIFIED = 0; // Version 1 of the ID uses EC-IES with SECP256R1 curve. ROOT_OF_TRUST_ID_VERSION_1 = 1; } optional RootOfTrustIdVersion version = 1; // The key_id is used for key rotation. It indicates which key was used to // generate the root of trust id. optional uint32 key_id = 2; // The EC-IES encrypted message containing the unique_id. The bytes are // a concatenation of // 1) The ephemeral public key. Uncompressed keypoint format per X9.62. // 2) The plaintext encrypted with the derived AES key using AES CBC, // PKCS7 padding and a zerio iv. // 3) The HMAC SHA256 of the cipher text. optional bytes encrypted_unique_id = 3; // The hash of encrypted unique id and other values. // unique_id_hash = SHA256( // encrypted_unique_id || system_id || SHA256(unique_id || secret_sauce)). optional bytes unique_id_hash = 4; } // DRM certificate definition for user devices, intermediate, service, and root // certificates. // Next id: 13 message DrmCertificate { enum Type { ROOT = 0; // ProtoBestPractices: ignore. DEVICE_MODEL = 1; DEVICE = 2; SERVICE = 3; PROVISIONER = 4; // Only used by internal L3 CDMs with baked-in (embedded) certificates that // support the Drm Reprovisioning method for individualization of embedded // certificates. DEVICE_EMBEDDED = 5; } enum ServiceType { UNKNOWN_SERVICE_TYPE = 0; LICENSE_SERVER_SDK = 1; LICENSE_SERVER_PROXY_SDK = 2; PROVISIONING_SDK = 3; CAS_PROXY_SDK = 4; } enum Algorithm { UNKNOWN_ALGORITHM = 0; RSA = 1; ECC_SECP256R1 = 2; ECC_SECP384R1 = 3; ECC_SECP521R1 = 4; } message EncryptionKey { // Device public key. PKCS#1 ASN.1 DER-encoded. Required. optional bytes public_key = 1; // Required. The algorithm field contains the curve used to create the // |public_key| if algorithm is one of the ECC types. // The |algorithm| is used for both to determine the if the certificate is // ECC or RSA. The |algorithm| also specifies the parameters that were used // to create |public_key| and are used to create an ephemeral session key. optional Algorithm algorithm = 2 [default = RSA]; } // Type of certificate. Required. optional Type type = 1; // 128-bit globally unique serial number of certificate. // Value is 0 for root certificate. Required. optional bytes serial_number = 2; // POSIX time, in seconds, when the certificate was created. Required. optional uint32 creation_time_seconds = 3; // POSIX time, in seconds, when the certificate should expire. Value of zero // denotes indefinite expiry time. For more information on limited lifespan // DRM certificates see (go/limited-lifespan-drm-certificates). optional uint32 expiration_time_seconds = 12; // Device public key. PKCS#1 ASN.1 DER-encoded. Required. optional bytes public_key = 4; // Widevine system ID for the device. Required for intermediate and // user device certificates. optional uint32 system_id = 5; // Deprecated field, which used to indicate whether the device was a test // (non-production) device. The test_device field in ProvisionedDeviceInfo // below should be observed instead. optional bool test_device_deprecated = 6 [deprecated = true]; // Service identifier (web origin) for the provider which owns the // certificate. Required for service and provisioner certificates. optional string provider_id = 7; // This field is used only when type = SERVICE to specify which SDK uses // service certificate. This repeated field is treated as a set. A certificate // may be used for the specified service SDK if the appropriate ServiceType // is specified in this field. repeated ServiceType service_types = 8; // Required. The algorithm field contains the curve used to create the // |public_key| if algorithm is one of the ECC types. // The |algorithm| is used for both to determine the if the certificate is ECC // or RSA. The |algorithm| also specifies the parameters that were used to // create |public_key| and are used to create an ephemeral session key. optional Algorithm algorithm = 9 [default = RSA]; // Optional. May be present in DEVICE certificate types. This is the root // of trust identifier that holds an encrypted value that identifies the // keybox or other root of trust that was used to provision a DEVICE drm // certificate. optional RootOfTrustId rot_id = 10; // Optional. May be present in devices that explicitly support dual keys. When // present the |public_key| is used for verification of received license // request messages. optional EncryptionKey encryption_key = 11; } // ---------------------------------------------------------------------------- // signed_drm_certificate.proto // ---------------------------------------------------------------------------- // Description of section: // Signed device certificate definition. // DrmCertificate signed by a higher (CA) DRM certificate. message SignedDrmCertificate { // Serialized certificate. Required. optional bytes drm_certificate = 1; // Signature of certificate. Signed with root or intermediate // certificate specified below. Required. optional bytes signature = 2; // SignedDrmCertificate used to sign this certificate. optional SignedDrmCertificate signer = 3; // Optional field that indicates the hash algorithm used in signature scheme. optional HashAlgorithmProto hash_algorithm = 4; }