zircon/system/ulib/tee-client-api/include/tee-client-api/tee_client_api.h - fuchsia - Git at Google

 // Copyright 2018 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #pragma once

 #include <stddef.h>
 #include <stdint.h>

 #include <zircon/compiler.h>

 #include <tee-client-api/tee-client-types.h>

 __BEGIN_CDECLS

 /*
  * Global Platform TEE Client API
  *
  * https://globalplatform.org/specs-library/tee-client-api-specification/
  *
  * This header contains Fuchsia's implementation of the functions, and by inclusion (#include), the
  * constants and data structures, that are defined by the Global Platform TEE Client API V1.0_c and
  * its associated Errata (V2.0).
  *
  * NOTE: The file name for this file uses underscores rather than Fuchsia's conventional dashes due
  * to the requirement from the Global Platform TEE Client API Spec that the header must be named
  * exactly 'tee_client_api.h'.
  */


 /*************
  * Functions *
  *************/

 /* TEEC_InitializeContext
  *
  * This function initializes a new TEE Context, forming a connection between this Client Application
  * and the TEE identified by the string identifier name.
  *
  * Parameters:
  * name     A zero-terminated string that describes the TEE to connect to. If this parameter is set
  *          to NULL the Implementation must select a default TEE.
  *
  * context  A TEEC_Context structre that must be initialized by the Implementation.
  *
  * Return:
  * TEEC_Result  TEEC_SUCCESS: Initialization was successful.
  *              Another error code: Initialization was not successful.
  */
 TEEC_Result TEEC_InitializeContext(const char* name, TEEC_Context* context);

 /* TEEC_FinalizeContext
  *
  * This function finalizes an initialized TEE Context, closing the connection between the Client
  * Application and the TEE. The Client Application MUST only call this function when all Sessions
  * inside this TEE Context have been closed and all Shared Memory blocks have been released.
  *
  * Parameters:
  * context  An initialized TEEC_Context structure which is to be finalized.
  */
 void TEEC_FinalizeContext(TEEC_Context* context);

 /* TEEC_RegisterSharedMemory
  *
  * This function registers a block of existing Client Application memory as a block of Shared Memory
  * within the scope of the specified TEE Context, in accordance with the parameters which have been
  * set by the Client Application inside the sharedMem structure.
  *
  * Parameters:
  * context      A pointer to an initialized TEE Context.
  *
  * sharedMem    A pointer to a Shared Memory structure to register:
  *                  The buffer, size, and flags fields of the sharedMem structure MUST be set in
  *                  accordance with the specification described above.
  *
  * Return:
  * TEEC_Result  TEEC_SUCCESS: The registration was successful.
  *              TEEC_ERROR_OUT_OF_MEMORY: The registration could not be completed because of a lack
  *                  of resources.
  *              Another error code: Registration was not successful for another reason.
  */
 TEEC_Result TEEC_RegisterSharedMemory(TEEC_Context* context, TEEC_SharedMemory* sharedMem);

 /* TEEC_AllocateSharedMemory
  *
  * This function allocates a new block of memory as a block of Shared Memory within the scope of the
  * specified TEE Context, in accordance with the parameters which have been set by the Client
  * Application inside the sharedMem structure.
  *
  * Parameters:
  * context      A pointer to an initialized TEE Context.
  *
  * sharedMem    A pointer to a Shared Memory structure to allocate:
  *                  * Before calling this function, the Client Application MUST have set the size,
  *                    and flags fields.
  *                  * On return, for a successful allocation the Implementation MUST have set the
  *                    pointer buffer to the address of the allocated block, otherwise it MUST set
  *                    buffer to NULL.
  *
  * Return:
  * TEEC_Result  TEEC_SUCCESS: The allocation was successful.
  *              TEEC_ERROR_OUT_OF_MEMORY: The allocation could not be completed due to resource
  *                  constraints.
  *              Another error code: Allocation was not successful for another reason.
  */
 TEEC_Result TEEC_AllocateSharedMemory(TEEC_Context* context, TEEC_SharedMemory* sharedMem);

 /* TEEC_ReleaseSharedMemory
  *
  * This function deregisters or deallocates a previously initialized block of Shared Memory.
  *
  * Parameters:
  * sharedMem    A pointer to a valid Shared Memory structure.
  */
 void TEEC_ReleaseSharedMemory(TEEC_SharedMemory* sharedMem);

 /* TEEC_OpenSession
  *
  * This function opens a new Session between the Client Application and the specified Trusted
  * Application.
  *
  * Parameters:
  * context          A pointer to an initialized TEE Context.
  *
  * session          A pointer to a Session structure to open.
  *
  * destination      A pointer to a structure containing the UUID of the destination Trusted
  *                  Application.
  *
  * connectionMethod The method of connection to use.
  *
  * connectionData   Any necessary data required to support the connection method chosen.
  *
  * operation        A pointer to an Operation containing a set of Parameters to exchange with the
  *                  Trusted Application, or NULL if no parameters are to be exchanged or if the
  *                  operation cannot be cancelled.
  *
  * returnOrigin     A pointer to a variable which will contain the return origin. This field may be
  *                  NULL if the return origin is not needed.
  *
  * Return:
  * TEEC_Result  * If the returnOrigin is different from TEEC_ORIGIN_TRUSTED_APP, a TEEC Return Code.
  *              * If the returnOrigin is equal to TEEC_ORIGIN_TRUSTED_APP, a return code defined by
  *                the protocol between the Client Application and the Trusted Application. In any
  *                case, a return code set to TEEC_SUCCESS means that the session was successfully
  *                opened and a return code different from TEEC_SUCCESS means that the session
  *                opening failed.
  */
 TEEC_Result TEEC_OpenSession(TEEC_Context* context,
                              TEEC_Session* session,
                              const TEEC_UUID* destination,
                              uint32_t connectionMethod,
                              const void* connectionData,
                              TEEC_Operation* operation,
                              uint32_t* returnOrigin);

 /* TEEC_CloseSession
  *
  * This function closes a Session which has been opened with a Trusted Application.
  *
  * Parameters:
  * session  The session to close.
  */
 void TEEC_CloseSession(TEEC_Session* session);

 /* TEEC_InvokeCommand
  *
  * This function invokes a Command within the specified Session.
  *
  * Parameters:
  * session      The open Session in which the command will be invoked.
  * commandID    The identifier of the Command within the Trusted Application to invoke. The meaning
  *              of each Command Identifier must be defined in the protocol exposed by the Trusted
  *              Application.
  * operation    A pointer to a Client Application initialized TEEC_Operation structure, or NULL if
  *              there is no payload to send or if the Command does not need to support cancellation.
  * returnOrigin A pointer to a variable which will contain the return origin. This field may be NULL
  *              if the return origin is not needed.
  *
  * Return:
  * TEEC_Result  * If the returnOrigin is different from TEEC_ORIGIN_TRUSTED_APP, a TEEC Return Code.
  *              * If the returnOrigin is TEEC_ORIGIN_TRUSTED_APP, a return code defined by the
  *                Trusted Application protocol.
  */
 TEEC_Result TEEC_InvokeCommand(TEEC_Session* session,
                                uint32_t commandID,
                                TEEC_Operation* operation,
                                uint32_t* returnOrigin);

 /* TEEC_RequestCancellation
  *
  * This function requests the cancellation of a pending open Session operation or a Command
  * invocation operation. As this is a synchronous API, this function must be called from a thread
  * other than the one executing the TEEC_OpenSession or TEEC_InvokeCommand function.
  *
  * Parameters:
  * operation    A pointer to a Client Application instantiated Operation structure.
  */
 void TEEC_RequestCancellation(TEEC_Operation* operation);

 __END_CDECLS
	// Copyright 2018 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#pragma once

	#include <stddef.h>
	#include <stdint.h>

	#include <zircon/compiler.h>

	#include <tee-client-api/tee-client-types.h>

	__BEGIN_CDECLS

	/*
	* Global Platform TEE Client API
	*
	* https://globalplatform.org/specs-library/tee-client-api-specification/
	*
	* This header contains Fuchsia's implementation of the functions, and by inclusion (#include), the
	* constants and data structures, that are defined by the Global Platform TEE Client API V1.0_c and
	* its associated Errata (V2.0).
	*
	* NOTE: The file name for this file uses underscores rather than Fuchsia's conventional dashes due
	* to the requirement from the Global Platform TEE Client API Spec that the header must be named
	* exactly 'tee_client_api.h'.
	*/



	/*************
	* Functions *
	*************/

	/* TEEC_InitializeContext
	*
	* This function initializes a new TEE Context, forming a connection between this Client Application
	* and the TEE identified by the string identifier name.
	*
	* Parameters:
	* name A zero-terminated string that describes the TEE to connect to. If this parameter is set
	* to NULL the Implementation must select a default TEE.
	*
	* context A TEEC_Context structre that must be initialized by the Implementation.
	*
	* Return:
	* TEEC_Result TEEC_SUCCESS: Initialization was successful.
	* Another error code: Initialization was not successful.
	*/
	TEEC_Result TEEC_InitializeContext(const char* name, TEEC_Context* context);

	/* TEEC_FinalizeContext
	*
	* This function finalizes an initialized TEE Context, closing the connection between the Client
	* Application and the TEE. The Client Application MUST only call this function when all Sessions
	* inside this TEE Context have been closed and all Shared Memory blocks have been released.
	*
	* Parameters:
	* context An initialized TEEC_Context structure which is to be finalized.
	*/
	void TEEC_FinalizeContext(TEEC_Context* context);

	/* TEEC_RegisterSharedMemory
	*
	* This function registers a block of existing Client Application memory as a block of Shared Memory
	* within the scope of the specified TEE Context, in accordance with the parameters which have been
	* set by the Client Application inside the sharedMem structure.
	*
	* Parameters:
	* context A pointer to an initialized TEE Context.
	*
	* sharedMem A pointer to a Shared Memory structure to register:
	* The buffer, size, and flags fields of the sharedMem structure MUST be set in
	* accordance with the specification described above.
	*
	* Return:
	* TEEC_Result TEEC_SUCCESS: The registration was successful.
	* TEEC_ERROR_OUT_OF_MEMORY: The registration could not be completed because of a lack
	* of resources.
	* Another error code: Registration was not successful for another reason.
	*/
	TEEC_Result TEEC_RegisterSharedMemory(TEEC_Context* context, TEEC_SharedMemory* sharedMem);

	/* TEEC_AllocateSharedMemory
	*
	* This function allocates a new block of memory as a block of Shared Memory within the scope of the
	* specified TEE Context, in accordance with the parameters which have been set by the Client
	* Application inside the sharedMem structure.
	*
	* Parameters:
	* context A pointer to an initialized TEE Context.
	*
	* sharedMem A pointer to a Shared Memory structure to allocate:
	* * Before calling this function, the Client Application MUST have set the size,
	* and flags fields.
	* * On return, for a successful allocation the Implementation MUST have set the
	* pointer buffer to the address of the allocated block, otherwise it MUST set
	* buffer to NULL.
	*
	* Return:
	* TEEC_Result TEEC_SUCCESS: The allocation was successful.
	* TEEC_ERROR_OUT_OF_MEMORY: The allocation could not be completed due to resource
	* constraints.
	* Another error code: Allocation was not successful for another reason.
	*/
	TEEC_Result TEEC_AllocateSharedMemory(TEEC_Context* context, TEEC_SharedMemory* sharedMem);

	/* TEEC_ReleaseSharedMemory
	*
	* This function deregisters or deallocates a previously initialized block of Shared Memory.
	*
	* Parameters:
	* sharedMem A pointer to a valid Shared Memory structure.
	*/
	void TEEC_ReleaseSharedMemory(TEEC_SharedMemory* sharedMem);

	/* TEEC_OpenSession
	*
	* This function opens a new Session between the Client Application and the specified Trusted
	* Application.
	*
	* Parameters:
	* context A pointer to an initialized TEE Context.
	*
	* session A pointer to a Session structure to open.
	*
	* destination A pointer to a structure containing the UUID of the destination Trusted
	* Application.
	*
	* connectionMethod The method of connection to use.
	*
	* connectionData Any necessary data required to support the connection method chosen.
	*
	* operation A pointer to an Operation containing a set of Parameters to exchange with the
	* Trusted Application, or NULL if no parameters are to be exchanged or if the
	* operation cannot be cancelled.
	*
	* returnOrigin A pointer to a variable which will contain the return origin. This field may be
	* NULL if the return origin is not needed.
	*
	* Return:
	* TEEC_Result * If the returnOrigin is different from TEEC_ORIGIN_TRUSTED_APP, a TEEC Return Code.
	* * If the returnOrigin is equal to TEEC_ORIGIN_TRUSTED_APP, a return code defined by
	* the protocol between the Client Application and the Trusted Application. In any
	* case, a return code set to TEEC_SUCCESS means that the session was successfully
	* opened and a return code different from TEEC_SUCCESS means that the session
	* opening failed.
	*/
	TEEC_Result TEEC_OpenSession(TEEC_Context* context,
	TEEC_Session* session,
	const TEEC_UUID* destination,
	uint32_t connectionMethod,
	const void* connectionData,
	TEEC_Operation* operation,
	uint32_t* returnOrigin);

	/* TEEC_CloseSession
	*
	* This function closes a Session which has been opened with a Trusted Application.
	*
	* Parameters:
	* session The session to close.
	*/
	void TEEC_CloseSession(TEEC_Session* session);

	/* TEEC_InvokeCommand
	*
	* This function invokes a Command within the specified Session.
	*
	* Parameters:
	* session The open Session in which the command will be invoked.
	* commandID The identifier of the Command within the Trusted Application to invoke. The meaning
	* of each Command Identifier must be defined in the protocol exposed by the Trusted
	* Application.
	* operation A pointer to a Client Application initialized TEEC_Operation structure, or NULL if
	* there is no payload to send or if the Command does not need to support cancellation.
	* returnOrigin A pointer to a variable which will contain the return origin. This field may be NULL
	* if the return origin is not needed.
	*
	* Return:
	* TEEC_Result * If the returnOrigin is different from TEEC_ORIGIN_TRUSTED_APP, a TEEC Return Code.
	* * If the returnOrigin is TEEC_ORIGIN_TRUSTED_APP, a return code defined by the
	* Trusted Application protocol.
	*/
	TEEC_Result TEEC_InvokeCommand(TEEC_Session* session,
	uint32_t commandID,
	TEEC_Operation* operation,
	uint32_t* returnOrigin);

	/* TEEC_RequestCancellation
	*
	* This function requests the cancellation of a pending open Session operation or a Command
	* invocation operation. As this is a synchronous API, this function must be called from a thread
	* other than the one executing the TEEC_OpenSession or TEEC_InvokeCommand function.
	*
	* Parameters:
	* operation A pointer to a Client Application instantiated Operation structure.
	*/
	void TEEC_RequestCancellation(TEEC_Operation* operation);

	__END_CDECLS