libteec: allow passing settings to context initialization

Add a new function, TEEC_InitializeContext2, that allows a developer to
pass configuration parameters in the form of distinct settings. One of the
new settings is for configuring OCALLs, where the caller sets a callback
handler for when an OCALL arrives from a TA.

Having multiple settings in this manner helps reduce the number of
auxiliary functions necessary. Were new functionality to be added in the
future, no new functions would need to be introduced. Instead, one would
only require a new setting.

Signed-off-by: Hernan Gatta <hegatta@microsoft.com>

libteec/src/tee_client_api.c

@@ -163,13 +163,62 @@ TEEC_Result TEEC_InitializeContext(const char *name, TEEC_Context *ctx)
 			ctx->reg_mem = gen_caps & TEE_GEN_CAP_REG_MEM;
 			ctx->memref_null = gen_caps & TEE_GEN_CAP_MEMREF_NULL;
 			ctx->ocall = gen_caps & TEE_GEN_CAP_OCALL;
+			ctx->ocall_setting.handler = NULL;
+			ctx->ocall_setting.data = NULL;
 			return TEEC_SUCCESS;
 		}
 	}
 
 	return TEEC_ERROR_ITEM_NOT_FOUND;
 }
 
+TEEC_Result TEEC_InitializeContext2(const char *name, TEEC_Context *ctx,
+				    const TEEC_ContextSetting *settings,
+				    uint32_t numSettings)
+{
+	uint32_t n;
+	TEEC_Result res;
+
+	if ((!settings && numSettings) || (settings && !numSettings))
+		return TEEC_ERROR_BAD_PARAMETERS;
+
+	if (settings) {
+		for (n = 0; n < numSettings; n++) {
+			switch (settings[n].type) {
+			case TEEC_CONTEXT_SETTING_OCALL:
+				if (!settings[n].u.ocall->handler)
+					return TEEC_ERROR_BAD_PARAMETERS;
+				break;
+			default:
+				return TEEC_ERROR_BAD_PARAMETERS;
+			}
+		}
+	}
+
+	res = TEEC_InitializeContext(name, ctx);
+	if (res != TEEC_SUCCESS)
+		return res;
+
+	for (n = 0; n < numSettings; n++) {
+		switch (settings[n].type) {
+		case TEEC_CONTEXT_SETTING_OCALL:
+			if (!ctx->ocall) {
+				TEEC_FinalizeContext(ctx);
+				return TEEC_ERROR_NOT_SUPPORTED;
+			}
+			ctx->ocall_setting.handler =
+				settings[n].u.ocall->handler;
+			ctx->ocall_setting.data = settings[n].u.ocall->data;
+			break;
+		default:
+			/* Not reached */
+			break;
+		}
+	}
+
+	return res;
+}
+
 void TEEC_FinalizeContext(TEEC_Context *ctx)
 {
 	if (ctx)

public/tee_client_api.h

@@ -248,17 +248,6 @@ extern "C" {
 
 typedef uint32_t TEEC_Result;
 
-/**
- * struct TEEC_Context - Represents a connection between a client application
- * and a TEE.
- */
-typedef struct {
-	/* Implementation defined */
-	int fd;
-	bool reg_mem;
-	bool memref_null;
-} TEEC_Context;
-
 /**
  * This type contains a Universally Unique Resource Identifier (UUID) type as
  * defined in RFC4122. These UUID values are used to identify Trusted
@@ -374,6 +363,72 @@ typedef union {
 	TEEC_Value value;
 } TEEC_Parameter;
 
+/**
+ * TEEC_Result (*TEEC_OcallHandler) - Type for a CA-provided function to call
+ * when the TA requests an OCALL.
+ *
+ * @param taUUID       UUID of the TA whence the OCALL originated.
+ * @param commandID    ID of the command the TA requests the CA execute.
+ * @param paramTypes   Type of data passed by the TA in the OCALL.
+ * @param params       Array of parameters of type TEEC_Parameter.
+ * @param ctxData      Arbitrary CA-provided pointer attached to the TEE
+ *                     context.
+ * @param sessionData  Arbitrary CA-provided pointer attached to the session.
+ */
+typedef TEEC_Result
+(*TEEC_OcallHandler)(TEEC_UUID *taUUID,
+		     uint32_t commandId,
+		     uint32_t paramTypes,
+		     TEEC_Parameter params[TEEC_CONFIG_PAYLOAD_REF_COUNT],
+		     void *ctxData,
+		     void *sessionData);
+
+/**
+ * enum TEEC_ContextSettingType - List of available settings when initializing a
+ * context.
+ */
+typedef enum {
+	TEEC_CONTEXT_SETTING_OCALL = 1
+} TEEC_ContextSettingType;
+
+/**
+ * struct TEEC_ContextSettingOcall - Setting to configure the behaviour of
+ * OCALLs.
+ *
+ * @param handler  Pointer to the function to execute to handle an OCALL.
+ * @param data     Arbitrary pointer to pass to the OCALL handler function.
+ */
+typedef struct {
+	TEEC_OcallHandler handler;
+	void *data;
+} TEEC_ContextSettingOcall;
+
+/**
+ * struct TEEC_ContextSetting - A setting to be used when opening a context.
+ *
+ * @param type  The type of setting this is (i.e., how to interpret the union).
+ * @param u     Union of all possible settings.
+ */
+typedef struct {
+	TEEC_ContextSettingType type;
+	union {
+		const TEEC_ContextSettingOcall *ocall;
+	} u;
+} TEEC_ContextSetting;
+
+/**
+ * struct TEEC_Context - Represents a connection between a client application
+ * and a TEE.
+ */
+typedef struct {
+	/* Implementation defined */
+	int fd;
+	bool reg_mem;
+	bool memref_null;
+	bool ocall;
+	TEEC_ContextSettingOcall ocall_setting;
+} TEEC_Context;
+
 /**
  * struct TEEC_Session - Represents a connection between a client application
  * and a trusted application.

public/tee_client_api_extensions.h

@@ -50,6 +50,28 @@ TEEC_Result TEEC_RegisterSharedMemoryFileDescriptor(TEEC_Context *context,
 						    TEEC_SharedMemory *sharedMem,
 						    int fd);
 
+/**
+ * TEEC_InitializeContext2() - Initializes a context holding connection
+ * information on the specific TEE, designated by the name string.
+
+ * @param name         A zero-terminated string identifying the TEE to connect
+ *                     to. If name is set to NULL, the default TEE is connected
+ *                     to. NULL is the only supported value in this version of
+ *                     the API implementation.
+ * @param context      The context structure which is to be initialized.
+ * @param settings     A list of settings to use to configure the new
+ *                     context, or NULL.
+ * @param numSettings  The number of settings, if any.
+ *
+ * @return TEEC_SUCCESS               The initialization was successful.
+ * @return TEEC_ERROR_BAD_PARAMETERS  One or more parameters are wrong.
+ * @return TEEC_ERROR_NOT_SUPPORTED   One or more settings are not supported.
+ * @return TEEC_Result                Something else failed.
+ */
+TEEC_Result TEEC_InitializeContext2(const char *name, TEEC_Context *ctx,
+				    const TEEC_ContextSetting *settings,
+				    uint32_t numSettings);
+
 #ifdef __cplusplus
 }
 #endif

typedefs.checkpatch

@@ -9,6 +9,10 @@ TEEC_Result
 TEEC_RegisteredMemoryReference
 TEEC_Parameter
 TEEC_Operation
+TEEC_OcallHandler
+TEEC_ContextSettingType
+TEEC_ContextSettingOcall
+TEEC_ContextSetting
 TEEC_Context
 CK_VOID_PTR_PTR
 CK_VOID_PTR