117 lines
4.4 KiB
C
117 lines
4.4 KiB
C
/*
|
|
* 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_ */
|