hostlib/hostLib/inc/HLSEObjects.h

/*
* @author NXP Semiconductors
* @version 1.0
* @par License
*
* Copyright 2017,2020 NXP
* SPDX-License-Identifier: Apache-2.0
*
*
* @par HISTORY
*
*/
/**
 * @file HLSEObjects.h
 * @par Description
 * Host Lib wrapper API: Object Operations
 */
#ifndef _HLSE_OBJECTS_H_
#define _HLSE_OBJECTS_H_

#include "HLSETypes.h"


// HLSE stands for: Host Library Secure Element


/**
* Enumerates all the Objects that currently exist on the Secure Element and have
\p objectType type. A list of object handles is returned in \p objectsHandles.

In order to enumerate all the Objects, set HLSE_ANY_TYPE in \p objectType.

Each object has a unique HLSE_OBJECT_HANDLE value - this value depends on the library implementation.

If \p objectHandles is NULL, then all that the function does is return (in \p *objectHandlesLen) a number of HLSE_OBJECT_HANDLE which would suffice
to hold the returned list.  HLSE_SW_OK is returned by the function.

If \p objectHandles is not NULL, then \p *objectHandlesLen must contain the number of handles in the buffer \p objectHandles.  If that buffer
is large enough to hold number of handles to be returned, then the handles are copied to \p objectHandles, and HLSE_SW_OK is returned by the function.
If the buffer is not large enough, then HLSE_ERR_BUF_TOO_SMALL is returned.  In either case, \p *objectHandlesLen is set to hold the exact number of
handles to be returned.

* \param[in] objectType The type of the Objects to be enumerated
* \param[in, out] objectHandles IN: caller passes a buffer of at least *objectHandlesLen; OUT: contains the handles of the objects
* \param[in, out] objectHandlesLen IN: number of handles in objectHandles. OUT: set to hold the exact number of handles in objectHandles.
*
* \retval ::HLSE_SW_OK Successfull execution
* \retval ::HLSE_ERR_BUF_TOO_SMALL Buffer is too small to return the handles
* \retval ::HLSE_ERR_API_ERROR Invalid function arguments
*/
HLSE_RET_CODE   HLSE_EnumerateObjects(HLSE_OBJECT_TYPE objectType, HLSE_OBJECT_HANDLE* objectHandles, U16* objectHandlesLen);

/**
* Creates or Generates an Object on the Secure Element, and returns a handle to it.

If the object already exists, it depends on the Secure Element behavior whether this function succeeds (e.g. set
a new value) or fail with an error.

\p attributes is an array of attributes that the object should be created with. Some of the attributes may be mandatory, such
as HLSE_ATTR_OBJECT_TYPE and HLSE_ATTR_OBJECT_INDEX (the id of the object), and some are optional.

In case there is a conflict in the attribute list (e.g. 2 differnt object types) it is the responsibility of the
library to detect it and return an error.

* \param[in] attributes The attributes to be used in creating the Object
* \param[in] attributesNum The number of attributes in \p attributes
* \param[in, out] hObject IN: A pointer to a handle (must not be NULL); OUT: The handle of the created Object
*
* \retval ::HLSE_SW_OK Successfull execution
* \retval ::HLSE_ERR_API_ERROR Invalid function arguments
*/
HLSE_RET_CODE   HLSE_CreateObject(HLSE_ATTRIBUTE* attributes, U16 attributesNum, HLSE_OBJECT_HANDLE* hObject);

/**
* Erases an object from the Secure Element.

This means the object with the specified handle can no longer be used.

* \param[in] hObject The handle of the Object to be erased
*
* \retval ::HLSE_SW_OK Successfull execution
*/
HLSE_RET_CODE   HLSE_EraseObject(HLSE_OBJECT_HANDLE hObject);

/**
* Sets the requested Attribute of the Object.

The parameter \p attribute may convey additinal information (e.g. a key value), in addition to the attribute's type.

* \param[in] hObject The handle of the Object that its attribute should be set
* \param[in] attribute The attribute to be Set
*
* \retval ::HLSE_SW_OK Successfull execution
* \retval ::HLSE_ERR_API_ERROR Invalid function arguments
*/
HLSE_RET_CODE   HLSE_SetObjectAttribute(HLSE_OBJECT_HANDLE hObject, HLSE_ATTRIBUTE* attribute);

/**
* Obtains the value of the Object's requested Attribute.

The parameter \p attribute specifies the Type of the attribute to be returned, and the data is
returned in the attribute's value and valueLen members.

If \p attribute->value is NULL, then all that the function does is return (in \p *attribute->valueLen) a number of bytes which would suffice
to hold the value to be returned.  HLSE_SW_OK is returned by the function.

If \p attribute->value is not NULL, then \p *attribute->valueLen must contain the number of bytes in the buffer \p attribute->value.  If that buffer
is large enough to hold the value be returned, then the data is copied to \p attribute->value, and HLSE_SW_OK is returned by the function.
If the buffer is not large enough, then HLSE_ERR_BUF_TOO_SMALL is returned.  In either case, \p *attribute->valueLen is set to hold the exact number of
bytes to be returned.


* \param[in] hObject The handle of the Object that its attribute's value should be obtained
* \param[in, out] attribute The attribute to be obtained
*
* \retval ::HLSE_SW_OK Successfull execution
* \retval ::HLSE_ERR_BUF_TOO_SMALL \p attribute->value is too small to return the data
* \retval ::HLSE_ERR_API_ERROR Invalid function arguments
*/
HLSE_RET_CODE   HLSE_GetObjectAttribute(HLSE_OBJECT_HANDLE hObject, HLSE_ATTRIBUTE* attribute);

// TBD: allow more than one attribute to be set/get in one call


/**
 * Debug Utility
 *
 * Force Read of GPDataTable from gp storage even if already in global memory variable
 *
 * NOTE!! : To be used only for internal testing and Debugging
 * ======
 * currently used to test the GP Table manipulation
 *
 * \retval ::HLSE_SW_OK Successfull execution
 */
HLSE_RET_CODE Debug_ForceReadGPDataTable(void);

#endif // _HLSE_OBJECTS_H_