First Publicly Shared Version of ODKiTEE v15

serialization/transport_interface.h

@@ -0,0 +1,116 @@
+/*
+ * 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_ */