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

#ifndef ODKITEE_TRANSPORT_INTERFACE_H_
#define ODKITEE_TRANSPORT_INTERFACE_H_

#ifdef __cplusplus
extern "C" {
#endif

/*
 * The Transport Interface is used by the oemcrypto library running
 * on the REE side/HLOS. It connects liboemcrypto to the trusted
 * OS's method of transporting data between the REE and the TEE.
 *
 * The trusted OS must provide primitives to transport data segments
 * between the REE and TEE. The maximum size of the data segments may
 * be fixed and predetermined by the trusted OS. However, the
 * transport implementation must be able to append data segments
 * sequentially to transport arbitrarily sized messages. For example
 * if the maximum block size is 2 KiB and a message is serialized that
 * requires 6 KiB, the transport layer must be able to extend the
 * messsage to three logically consecutive 2 KiB segments during
 * serialization to contain the message. Messages may be initially
 * allocated at any block size. The serialization layer will call back
 * into the transport layer to request that additional blocks be added
 * to the message as needed. The serialization layer will attempt to
 * minimize the actual size of messages by passing larger parameters
 * in shared memory, if supported by the trusted OS.
 *
 * Functions need to be provided to allocate, extend and deallocate
 * messages, and send and receive messages between the REE and the
 * TEE.
 */

typedef enum {
  /*
   * ODK_TRANSPORT_STATUS_OK must be returned from transport functions
   * if the requested operation completed succesfully.
   */
  ODK_TRANSPORT_STATUS_OK,

  /*
   * ODK_TRANSPORT_STATUS_ALLOC_FAILED must be returned from
   * ODK_Transport_ExtendMessage if there is insufficient memory. This
   * is a fatal failure that will cause OEMCrypto to return
   * OEMCrypto_ERROR_INSUFFICIENT_RESOURCES.
   */
  ODK_TRANSPORT_STATUS_ALLOC_FAILED,

  /*
   * ODK_TRANSPORT_STATUS_IO_ERROR must be returned from
   * ODK_Transport_SendMessage or ODK_Transport_ReceiveMessage if the
   * transport interface was unable to deliver or receive a message
   * for any reason. The transport implementation should be designed
   * to be robust against communication failures, e.g. by providing
   * logic to retry delivery or other techniques if possible. The
   * odkitee library does not make any attempts to improve
   * communcation reliability using these techniques.
   *
   * This return code indicates a fatal failure of the current command
   * which will result in OEMCrypto returning
   * OEMCrypto_ERROR_SYSTEM_INVALIDATED. This will cause the app to be
   * notified that the drm system must be reinitialized.
   */
  ODK_TRANSPORT_STATUS_IO_ERROR,
} ODK_Transport_Status;

/*
 * Allocate a new message of a size that is determined by the
 * transport implementation, which is most likely the maximum data
 * segment transport size of the trusted OS. The message will be
 * subsequently extended if it is too small for the message currently
 * being serialized. Must return NULL if the transport implementation
 * is unable to allocate a message of any size. Only two messages will
 * be simultaneously allocated at any time.
 */
Message* ODK_Transport_AllocateMessage(void);

/*
 * Extend an existing message to a new size. The new size is the total
 * required size of the message including the currently allocation
 * portion. Return ODK_TRANSPORT_STATUS_ALLOC_FAILED if the transport
 * interface is unable to extend the message to the new size.
 */
ODK_Transport_Status ODK_Transport_ExtendMessage(Message* message, size_t new_size);

/*
 * Request that a message be delivered from the REE to the TEE. If the
 * delivery is successful ODK_TRANSPORT_STATUS_OK must be returned.
 * Otherwise return ODK_TRANSPORT_STATUS_IO_ERROR.
 */
ODK_Transport_Status ODK_Transport_SendMessage(Message* message);

/*
 * Request that a message be received by the REE from the TEE. If
 * the receipt is successful ODK_TRANSPORT_STATUS_OK must be returned.
 * Otherwise return ODK_TRANSPORT_STATUS_IO_ERROR.
 */
ODK_Transport_Status ODK_Transport_ReceiveMessage(Message** message);

/*
 * Return a message that is not longer in use to the transport
 * interface.
 */
void ODK_Transport_DeallocateMessage(Message* message);


#ifdef __cplusplus
}  // extern "C"
#endif

#endif /* ODKITEE_TRANSPORT_INTERFACE_H_ */