provisioning_sdk/protos/public/certificate_provisioning.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:
//   Public protocol buffer definitions for Widevine Device Certificate
//   Provisioning protocol.

syntax = "proto2";

package widevine;

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

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


// 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 iff 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;
}

// 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
// mE_ZP4WmSX-JNldg
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;
  // Optional field that indicates the hash algorithm used in signature scheme.
  optional HashAlgorithmProto hash_algorithm = 3;
}

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

  // 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", found internally
  // at
  // https://docs.google.com/document/d/1M5f0OA8zrIFufpZiny_M9WkvJkCUs9DpRpeDmk9QKKY/edit
  optional bytes oemcrypto_core_message = 6;
  // Optional field that indicates the hash algorithm used in signature scheme.
  optional HashAlgorithmProto hash_algorithm = 7;
}