android/libwvdrmengine/oemcrypto/odk/kdo/include/oec_util.h

/*
 * Copyright 2019 Google LLC. All Rights Reserved. This file and proprietary
 * source code may only be used and distributed under the Widevine Master
 * License Agreement.
 */

// clang-format off
/*********************************************************************
 * oec_util.h
 *
 * OEMCrypto v16 Core Message Serialization library counterpart (a.k.a. KDO)
 *
 * For Widevine Modular DRM, there are six message types between a server and
 * a client device: license request and response, provisioning request and
 * response, and renewal request and response.
 *
 * In OEMCrypto v15 and earlier, messages from the server were parsed by the
 * CDM layer above OEMCrypto; the CDM in turn gave OEMCrypto a collection of
 * pointers to protected data within the message. However, the pointers
 * themselves were not signed by the server.
 *
 * Starting from OEMCrypto v16, all fields used by OEMCrypto in each of these
 * messages have been identified in the document "Widevine Core Message
 * Serialization". These fields are called the core of the message. Core
 * message fields are (de)serialized using the ODK, a C library provided by
 * Widevine. OEMCrypto will parse and verify the core of the message with
 * help from the ODK.
 *
 * The KDO library is the counterpart of ODK used in the CDM & Widevine
 * servers. For each message type generated by the ODK, KDO provides a
 * corresponding parser. For each message type to be parsed by the ODK,
 * KDO provides a corresponding writer.
 *
 * Table: ODK vs KDO (s: serialize; d: deserialize)
 * +----------------------------------------+------------------------------------+
 * | ODK                                    | KDO                                |
 * +---+------------------------------------+---+--------------------------------+
 * | s | ODK_PrepareCoreLicenseRequest      | d | ParseLicenseRequest            |
 * |   +------------------------------------+   +--------------------------------+
 * |   | ODK_PrepareCoreRenewalRequest      |   | ParseRenewalRequest            |
 * |   +------------------------------------+   +--------------------------------+
 * |   | ODK_PrepareCoreProvisioningRequest |   | ParseProvisioningRequest       |
 * +---+------------------------------------+---+--------------------------------+
 * | d | ODK_ParseLicense                   | s | CreateCoreLicenseResponse      |
 * |   +------------------------------------+   +--------------------------------+
 * |   | ODK_ParseRenewal                   |   | CreateCoreRenewalResponse      |
 * |   +------------------------------------+   +--------------------------------+
 * |   | ODK_ParseProvisioning              |   | CreateCoreProvisioningResponse |
 * +---+------------------------------------+---+--------------------------------+
 *
 *********************************************************************/
// clang-format on

#ifndef OEC_UTIL_H_
#define OEC_UTIL_H_

#include <cstdint>
#include <string>

#include "odk_structs.h"

using namespace std;

namespace oec_util {

// @ input/output structs

/**
 * Output structure for ParseLicenseRequest
 * Input structure for CreateCoreLicenseResponse
 */
struct ODK_LicenseRequest {
  uint32_t api_version;
  uint32_t nonce;
  uint32_t session_id;
};

/**
 * Output structure for ParseRenewalRequest
 * Input structure for CreateCoreRenewalResponse
 */
struct ODK_RenewalRequest {
  uint32_t api_version;
  uint32_t nonce;
  uint32_t session_id;
  uint64_t playback_time;
};

/**
 * Output structure for ParseProvisioningRequest
 * Input structure for CreateCoreProvisioningResponse
 */
struct ODK_ProvisioningRequest {
  uint32_t api_version;
  uint32_t nonce;
  uint32_t session_id;
  string device_id;
};

// @ public parse request (deserializer) functions

/**
 * Counterpart (deserializer) of ODK_PrepareCoreLicenseRequest (serializer)
 *
 * Parameters:
 *   [in] oemcrypto_core_message
 *   [out] core_license_request
 */
bool ParseLicenseRequest(const string& oemcrypto_core_message,
                         ODK_LicenseRequest* core_license_request);

/**
 * Counterpart (deserializer) of ODK_PrepareCoreRenewalRequest (serializer)
 *
 * Parameters:
 *   [in] oemcrypto_core_message
 *   [out] core_renewal_request
 */
bool ParseRenewalRequest(const string& oemcrypto_core_message,
                         ODK_RenewalRequest* core_renewal_request);

/**
 * Counterpart (deserializer) of ODK_PrepareCoreProvisioningRequest (serializer)
 *
 * Parameters:
 *   [in] oemcrypto_core_message
 *   [out] core_provisioning_request
 */
bool ParseProvisioningRequest(
    const string& oemcrypto_core_message,
    ODK_ProvisioningRequest* core_provisioning_request);

// @ public create response (serializer) functions

/**
 * Counterpart (serializer) of ODK_ParseLicense (deserializer)
 * struct-input variant
 *
 * Parameters:
 *   [in] parsed_lic
 *   [in] core_request
 *   [out] oemcrypto_core_message
 */
bool CreateCoreLicenseResponse(const ODK_ParsedLicense& parsed_lic,
                               const ODK_LicenseRequest& core_request,
                               string* oemcrypto_core_message);

/**
 * Counterpart (serializer) of ODK_ParseRenewal (deserializer)
 *
 * Parameters:
 *   [in] core_request
 *   [out] oemcrypto_core_message
 */
bool CreateCoreRenewalResponse(const ODK_RenewalRequest& core_request,
                               string* oemcrypto_core_message);

/**
 * Counterpart (serializer) of ODK_ParseProvisioning (deserializer)
 * struct-input variant
 *
 * Parameters:
 *   [in] parsed_prov
 *   [in] core_request
 *   [out] oemcrypto_core_message
 */
bool CreateCoreProvisioningResponse(const ODK_ParsedProvisioning& parsed_prov,
                                    const ODK_ProvisioningRequest& core_request,
                                    string* oemcrypto_core_message);
}  // namespace oec_util

#endif  // OEC_UTIL_H_