10.4. A71CH Legacy HLSE (Generic) API¶
10.4.1. HLSE API¶
The API is designed to be generic for Secure Elements that hold cryptographic information and perform cryptographic functions. It isolates an application from the details of the cryptographic device such that it does not have to change to interface to a different type of cryptographic device.
This generic layer intends to abstract both the different APDU specs of applets, and the ?file system? details, i.e., how each ?object? is stored on the SE. For example, in order to enumerate the certificate objects on the card, the implementation should know where the objects are located, how many there are, what their type is, etc. This abstract layer is important for, e.g. a PKCS#11 layer, and for TLS engines that will have to access objects on the Secure Element.
The HLSE API is written in C allowing maximal portability across different platforms.
Each typedef, enum and function starts with the HLSE (=Host Library Secure Element) prefix.
The various Secure Element entities are referred to as Objects. Every Object (e.g. Key) has a unique handle (HLSE_OBJECT_HANDLE) and a set of attributes (HLSE_ATTRIBUTE) whose values can be retrieved (Get) and Set. An HLSE_OBJECT_HANDLE can be obtained in two ways: Either returned by HLSE_EnumerateObjects() if the Object exists on the Secure Element, or returned by HLSE_CreateObject() for a new Object. This is an abstraction of the actual way in which the API implements these handles.
An HLSE_ATTRIBUTE is defined as:
typedef struct HLSE_ATTRIBUTE {
HLSE_ATTRIBUTE_TYPE type;
void* value;
U16 valueLen;
} HLSE_ATTRIBUTE;
For example, a Private RSA key may have the HLSE_ATTR_RSA_MODULUS and HLSE_ATTR_RSA_PUBLIC_EXPONENT attributes, and their values can be extracted or set.
Key Generation can be obtained by passing a NULL parameter in the HLSE_ATTR_OBJECT_VALUE attribute. This enables to create the key with a generated random data, or to re-generate an existing key by passing NULL in this attribute’s parameter.
A set of functions is responsible for performing cryptographic operations:
HLSE_Digest()
HLSE_Sign()
HLSE_VerifySignature()
HLSE_DeriveKey()
HLSE_Encrypt()
HLSE_Decrypt()
The cryptographic algorithm is controlled by a HLSE_MECHANISM_INFO, defined as:
typedef struct HLSE_MECHANISM_INFO {
HLSE_MECHANISM_TYPE mechanism;
void* pParameter;
U16 ulParameterLen;
} HLSE_MECHANISM_INFO;
A list of the supported mechanisms, either by the library or by a specific key, can be obtained by calling HLSE_GetSupportedMechanisms() or HLSE_GetSupportedMechanismsForObject(), respectively.
The HLSE API is made up of four parts:
Operations on Objects (HLSEObjects.h)
Cryptographic operations (HLSECrypto.h)
Secure Element Communication and Secure Channel management functions (HLSEComm.h)
Debug Mode variant and miscellaneous functionality (HLSEMisc.h)
An additional file .../hostLib/inc/HLSEAPI.h
serves as an entry point to the full API.
The implementation of the API dealing with A71CH specific functionality is in .../hostLib/api/src/A71HLSEWrapper.c
.
10.4.2. Logical objects¶
The HLSE API allows to create logical objects in the GP Storage. They can be of HLSE_CERTIFICATE or HLSE_DATA object type. The abstraction for various objects that reside in the GP Storage area is achieved by maintaining a lookup table (mapping) at the end of the GP Storage area to hold information about the logical objects that exist in the GP Storage. The structure of the table is as follows:
Notes:
X+1 is the address of the last byte of the GP Storage.
N is the object number from 1 to N
Address Value
------- ----------------------
X-N*6+0 N'th Object Class - 1 byte
X-N*6+1 N'th Object Index - 1 byte
X-N*6+2 N'th Object Length MSB - 1 byte
X-N*6+3 N'th Object Length LSB - 1 byte
X-N*6+4 N'th Object Offset MSB - 1 byte
X-N*6+5 N'th Object Offset LSB - 1 byte
?
X-1*6+0 First Object Class - 1 byte
X-1*6+1 First Object Index - 1 byte
X-1*6+2 First Object Length MSB - 1 byte
X-1*6+3 First Object Length LSB - 1 byte
X-1*6+4 First Object Offset MSB - 1 byte
X-1*6+5 First Object Offset LSB - 1 byte
X Update Counter - 1 byte
X+1 Number of table entries - 1 byte
End of GP Storage
The table will be written so that the ‘Number of table entries’ byte is the last byte of the GP Data (to allow the map to grow dynamically as long as there is enough free space), preceded by one byte of the Update Counter and then preceded by 6-tuples of entries.
The Class byte is equivalent to the object type using a single byte (0x09 for Certificate, 0x0A for Data).
The order of the 6-tuple entries is not important, as each object is identified by its Class and Index. In cases where the length of an object is not known at the time the lookup table entry is created, the MSBit (0x8000) can be set in the length as an indicator that the data is in TLV format and that the actual length must be obtained by reading the first bytes of the object’s data.
For objects of type ‘Certificate’ the provisioned ‘Object Length’ value must be one of the following:
The reserved object storage length (allowing for a possible increase in size of the certificate or for die-individual variance of the certificate size).
The actual certificate length
In the exceptional case neither a reserved certificate object storage length nor the effective certificate length can be determined one can use the value ‘0x8000’ to indicate the ‘Object Size’ is unknown at the time of provisioning.
When reading a certificate from GP storage with the HLSE API, the size of the certificate is always determined by the length value of the certificate’s initial TL(V) header.
The host library reads the total number of entries in the table from the last byte of the GP Data, followed by parsing/reading the 6-tuple entries. Up to 254 (0xFE) objects are assumed. A value of 0xFF in the number of entries indicates that the table is absent (uninitialized) or invalid.
Class and Index value of 0xFF indicates an invalid entry (i.e. of a deleted object).
The Update Counter is initially set to 0 and it is incremented on each table update. This serves as an indication to a GP Storage’s change when there is more than one application updating the SE concurrently.
The value of ‘object offset’ must be a multiple of 32.
It is not allowed to create a data object of size 0.
10.4.2.1. Object creation¶
The library supports a dynamic number of objects in the GP Storage, according to the memory availability.
Creating an object through HLSE_CreateObject() requires the following attributes to be passed:
HLSE_ATTR_OBJECT_TYPE ? currently HLSE_CERTIFICATE or HLSE_DATA;
HLSE_ATTR_OBJECT_INDEX ? will be the Tag of the object, 1 byte;
HLSE_ATTR_OBJECT_VALUE ? the object’s value.
An additional attribute that can only be passed in Create is HLSE_ATTR_READ_ONLY. Setting this value to 1 will lock (‘freeze’) the memory associated with the object (once it has been created) so it cannot be modified. The HLSE_ATTR_READ_ONLY attribute is not explicitly stored in the GP Storage lookup table.
Note that this attribute cannot be set after object creation. If not passed, it has a default value of 0 (can be modified).
Creation fails if there is not enough continuous unlocked space for the new object’s value.
10.4.2.2. Value Update¶
It is possible to change the object’s value by calling HLSE_SetObjectAttribute() with HLSE_ATTR_OBJECT_VALUE. If the object needs to be enlarged, it is only permitted if enough memory is available for the object to grow, case as follows:
1. Within the same GP Storage’s chunk size (32 bytes), so that the same amount of storage chunks will be used - For example, if the size was originally 21 bytes then the object occupies 1 chunk, and it is possible to enlarge it up to 32 bytes. 2. Up to the offset of the next allocated object in the GP memory.
If a larger size is required, the object must first be erased and then re-created (assuming a sufficiently large continuous unlocked space is available in GP memory).
10.4.2.3. Direct Access Value Update¶
It is possible to change a sub section of a Data object’s value by calling HLSE_SetObjectAttribute() with HLSE_ATTR_DIRECT_ACCESS_OBJECT_VALUE, where the value should point to a HLSE_DIRECT_ACCESS_ATTRIBUTE_VALUE structure that passes the offset, number of bytes to read and the buffer. The update is only permitted within the object’s GP Storage’s chunk boundary.
10.4.2.4. Erasing an object¶
To erase an object first fetch its handle with HLSE_EnumerateObjects() and call HLSE_EraseObject(). Erasing an object only invalidates its lookup table entry, it does not erase its value contents in the GP Storage, due to performance reasons.
10.4.2.5. Interoperability of Object storage and locked chunks¶
The following defines the behavior of the HLSE API when updating (full/partial) or erasing partially locked objects stored in GP memory:
When updating an object (by definition this concerns the complete object) the HLSE API first checks that no chunk of the object is locked before updating the object.
When doing a partial update of an object the HLSE API does not check whether the affected memory chunks(s) are locked or unlocked. The partial update will fail or succeed accordingly. Consequently one must only issue a partial update of an object for chunks that are unlocked.
When erasing an object, the HLSE_EnumerateObjects() API checks whether the first chunk of the object is locked. If the first chunk is not locked the entry corresponding to the object is removed from the GP lookup table. If the first chunk is locked, the object is considered ‘read-only’ and the object is not removed from the GP lookup table. As explained above, erasing an object does not erase the value associated with the object.
Locking the GP storage chunks containing the lookup table (even a partial lock) will make it impossible to remove, add or update objects.
10.4.2.6. Notes¶
If the applet is Trust Provisioned prior to being shipped to the user, with e.g. one or more certificate(s), then the lookup table is expected to be in the GP Data.
If the lookup table is missing (invalid value), then it is automatically created by the host library upon the first call to CreateObject of such an object.
When reading a certificate, the response omits any trailing padding at the end of the certificate. The size of the certificate is determined by the length value of the certificates initial TL(V) header.
When updating an Object - the length in the GP table will be kept as the maximum size of the existing and new the object. As a consequence, it’s not possible to shrink the size of an object by updating it.
Don’t use direct A71CH API access in combination with the HLSE Object API as one can damage the lookup table or the value of stored objects.
10.4.3. API details¶
10.4.3.1. HLSEObjects.h¶
- Description
Host Lib wrapper API: Object Operations
Functions
-
HLSE_RET_CODE
HLSE_EnumerateObjects
(HLSE_OBJECT_TYPE objectType, HLSE_OBJECT_HANDLE *objectHandles, U16 *objectHandlesLen) Enumerates all the Objects that currently exist on the Secure Element and have
objectType
type. A list of object handles is returned inobjectsHandles
.In order to enumerate all the Objects, set HLSE_ANY_TYPE in
objectType
.Each object has a unique HLSE_OBJECT_HANDLE value - this value depends on the library implementation.
If
objectHandles
is NULL, then all that the function does is return (in*objectHandlesLen
) a number of HLSE_OBJECT_HANDLE which would suffice to hold the returned list. HLSE_SW_OK is returned by the function.If
objectHandles
is not NULL, then*objectHandlesLen
must contain the number of handles in the bufferobjectHandles
. If that buffer is large enough to hold number of handles to be returned, then the handles are copied toobjectHandles
, 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,*objectHandlesLen
is set to hold the exact number of handles to be returned.- Parameters
[in] objectType
: The type of the Objects to be enumerated[inout] objectHandles
: IN: caller passes a buffer of at least *objectHandlesLen; OUT: contains the handles of the objects[inout] objectHandlesLen
: IN: number of handles in objectHandles. OUT: set to hold the exact number of handles in objectHandles.
- Return Value
HLSE_SW_OK
: Successfull executionHLSE_ERR_BUF_TOO_SMALL
: Buffer is too small to return the handlesHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_CreateObject
(HLSE_ATTRIBUTE *attributes, U16 attributesNum, HLSE_OBJECT_HANDLE *hObject) 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.
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.
- Parameters
[in] attributes
: The attributes to be used in creating the Object[in] attributesNum
: The number of attributes inattributes
[inout] hObject
: IN: A pointer to a handle (must not be NULL); OUT: The handle of the created Object
- Return Value
HLSE_SW_OK
: Successfull executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_EraseObject
(HLSE_OBJECT_HANDLE hObject) Erases an object from the Secure Element.
This means the object with the specified handle can no longer be used.
- Parameters
[in] hObject
: The handle of the Object to be erased
- Return Value
HLSE_SW_OK
: Successfull execution
-
HLSE_RET_CODE
HLSE_SetObjectAttribute
(HLSE_OBJECT_HANDLE hObject, HLSE_ATTRIBUTE *attribute) Sets the requested Attribute of the Object.
The parameter
attribute
may convey additinal information (e.g. a key value), in addition to the attribute’s type.- Parameters
[in] hObject
: The handle of the Object that its attribute should be set[in] attribute
: The attribute to be Set
- Return Value
HLSE_SW_OK
: Successfull executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_GetObjectAttribute
(HLSE_OBJECT_HANDLE hObject, HLSE_ATTRIBUTE *attribute) Obtains the value of the Object’s requested Attribute.
The parameter
attribute
specifies the Type of the attribute to be returned, and the data is returned in the attribute’s value and valueLen members.If
attribute->value
is NULL, then all that the function does is return (in*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
attribute->value
is not NULL, then*attribute->valueLen
must contain the number of bytes in the bufferattribute->value
. If that buffer is large enough to hold the value be returned, then the data is copied toattribute->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,*attribute->valueLen
is set to hold the exact number of bytes to be returned.- Parameters
[in] hObject
: The handle of the Object that its attribute’s value should be obtained[inout] attribute
: The attribute to be obtained
- Return Value
HLSE_SW_OK
: Successfull executionHLSE_ERR_BUF_TOO_SMALL
:attribute->value
is too small to return the dataHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
Debug_ForceReadGPDataTable
(void) 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
- Return Value
HLSE_SW_OK
: Successfull execution
10.4.3.2. HLSECrypto.h¶
- Description
Host Lib wrapper API: Cryptographic functions
Functions
-
HLSE_RET_CODE
HLSE_GetSupportedMechanisms
(HLSE_MECHANISM_TYPE *mechanisms, U16 *mechanismNum) Enumerates all the Cryptographic Mechanisms that are supported by the library. A list of mechanisms is returned in
mechanisms
.If
mechanisms
is NULL, then all that the function does is return (in*mechanismNum
) the number of HLSE_MECHANISM_TYPE which would suffice to hold the returned list. HLSE_SW_OK is returned by the function.If
mechanisms
is not NULL, then*mechanismNum
must contain the number of mechanisms in the buffermechanisms
. If that buffer is large enough to hold number of mechanisms to be returned, then the mechanisms are copied tomechanisms
, 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,*mechanismNum
is set to hold the exact number of mechanisms to be returned.- Parameters
[inout] mechanisms
: IN: caller passes a buffer of at least *mechanismNum; OUT: contains the mechanisms supported[inout] mechanismNum
: IN: number of mechanisms in mechanisms; OUT: set to hold the exact number of mechanisms
- Return Value
HLSE_SW_OK
: Successfull executionHLSE_ERR_BUF_TOO_SMALL
: Buffer is too small to return the mechanismsHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_GetSupportedMechanismsForObject
(HLSE_OBJECT_HANDLE hObject, HLSE_MECHANISM_TYPE *mechanism, U16 *mechanismLen) Enumerates all the Cryptographic Mechanisms that are supported by the Object. A list of mechanisms is returned in
mechanisms
.If
mechanism
is NULL, then all that the function does is return (in*mechanismLen
) the number of HLSE_MECHANISM_TYPE which would suffice to hold the returned list. HLSE_SW_OK is returned by the function.If
mechanism
is not NULL, then*mechanismLen
must contain the number of mechanisms in the buffermechanisms
. If that buffer is large enough to hold number of mechanisms to be returned, then the mechanisms are copied tomechanisms
, 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,*mechanismLen
is set to hold the exact number of mechanisms to be returned.- Parameters
[in] hObject
: The handle of the Object that the Mechanisms it supports should be returned[inout] mechanism
: IN: caller passes a buffer of at least *mechanismNum; OUT: contains the mechanisms supported[inout] mechanismLen
: IN: number of mechanisms in mechanisms. OUT: set to hold the exact number of mechanisms
- Return Value
HLSE_SW_OK
: Successfull executionHLSE_ERR_BUF_TOO_SMALL
: Buffer is too small to return the mechanismsHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_Digest
(HLSE_MECHANISM_INFO *pMechanismType, U8 *inData, U16 inDataLen, U8 *outDigest, U16 *outDigestLen) Calculates the Digest (e.g. Sha256) value of the data provided as input.
The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter.If additional information is required by the specific digest mechanism, is will be conveyed in
pMechanismType->pParameter
.If
outDigest
is NULL, then all that the function does is return (in*outDigestLen
) a number of bytes which would suffice to hold the digest value. HLSE_SW_OK is returned by the function.If
outDigest
is not NULL, then*outDigestLen
must contain the number of bytes in the bufferoutDigest
. If that buffer is large enough to hold the digest value be returned, then the data is copied tooutDigest
, 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,*outDigestLen
is set to hold the exact number of bytes to be returned.- Parameters
[in] pMechanismType
: The Digest Cryptographic Mechanism to be used[in] inData
: Data buffer for which the digest must be calculated[in] inDataLen
: The length of data passed as argument[inout] outDigest
: IN: caller passes a buffer to hold the digest value; OUT: contains the calculated digest[inout] outDigestLen
: IN: length of theoutDigest
buffer passed; OUT: the number of bytes returned inoutDigest
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_BUF_TOO_SMALL
:outDigest
is too small to return the digestHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_Sign
(HLSE_MECHANISM_INFO *pMechanismType, HLSE_OBJECT_HANDLE hObject, U8 *inData, U16 inDataLen, U8 *outSignature, U16 *outSignatureLen) Signs the data provided using the Object key and the requested mechanism.
The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter. A handle to the key to sign the data with is provided byhObject
.If additional information is required by the specific signing mechanism, is will be conveyed in
pMechanismType->pParameter
.If
outSignature
is NULL, then all that the function does is return (in*outSignatureLen
) a number of bytes which would suffice to hold the signature. HLSE_SW_OK is returned by the function.If
outSignature
is not NULL, then*outSignatureLen
must contain the number of bytes in the bufferoutSignature
. If that buffer is large enough to hold the signature be returned, then the data is copied tooutSignature
, 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,*outSignatureLen
is set to hold the exact number of bytes to be returned.- Parameters
[in] pMechanismType
: The signing Cryptographic Mechanism to be used[in] hObject
: The handle of the Object key to sign with[in] inData
: Data buffer for that should be signed (e.g. a digest)[in] inDataLen
: The length of data passed as argument[inout] outSignature
: IN: caller passes a buffer to hold the signature; OUT: contains the calculated signature[inout] outSignatureLen
: IN: length of theoutSignature
buffer passed; OUT: the number of bytes returned inoutSignature
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_BUF_TOO_SMALL
:outSignature
is too small to return the signatureHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_VerifySignature
(HLSE_MECHANISM_INFO *pMechanismType, HLSE_OBJECT_HANDLE hObject, U8 *inData, U16 inDataLen, U8 *inSignature, U16 inSignatureLen) Verifies whether
inSignature
is the signature ofinData
using the public key object referenced byhObject
as the verifying public key.The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter.- Parameters
[in] pMechanismType
: The signing Cryptographic Mechanism that was used[in] hObject
: The handle of the Object public key to verify with[in] inData
: The data that was signed (e.g. a digest)[in] inDataLen
: The length of data passed as argument[in] inSignature
: Pointer to the provided signature.[in] inSignatureLen
: Length of the provided signature (pSignature
)
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_GENERAL_ERROR
: if the verification fails
-
HLSE_RET_CODE
HLSE_VerifySignatureWithExternalKey
(HLSE_MECHANISM_INFO *pMechanismType, U8 *inExtKey, U16 inExtKeyLen, U8 *inData, U16 inDataLen, U8 *inSignature, U16 inSignatureLen) Verifies whether
inSignature
is the signature ofinData
using an external public key object as the verifying public key.The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter.- Parameters
[in] pMechanismType
: The signing Cryptographic Mechanism that was used[in] inExtKey
: The value of the external public key to verify with[in] inExtKeyLen
: The length in bytes of the external key[in] inData
: The data that was signed (e.g. a digest)[in] inDataLen
: The length of data passed as argument[in] inSignature
: Pointer to the provided signature.[in] inSignatureLen
: Length of the provided signature (pSignature
)
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_GENERAL_ERROR
: if the verification fails
-
HLSE_RET_CODE
HLSE_DeriveKey
(HLSE_MECHANISM_INFO *pMechanismType, HLSE_OBJECT_HANDLE hObject, U8 *outDerivedKey, U16 *outDerivedKeyLen) Derives the key referenced by the
hObject
handle using the requested mechanism and return the derived key inoutDerivedKey
.The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter.If additional information is required by the specific signing mechanism, is will be conveyed in
pMechanismType->pParameter
.If
outDerivedKey
is NULL, then all that the function does is return (in*outDerivedKeyLen
) a number of bytes which would suffice to hold the derived key. HLSE_SW_OK is returned by the function.If
outDerivedKey
is not NULL, then*outDerivedKeyLen
must contain the number of bytes in the bufferoutDerivedKey
. If that buffer is large enough to hold the derived key, then the data is copied tooutDerivedKey
, 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,*outDerivedKeyLen
is set to hold the exact number of bytes of the derived key.- Parameters
[in] pMechanismType
: The signing Cryptographic Mechanism to be used[in] hObject
: The handle of the Object key to be derived[inout] outDerivedKey
: IN: caller passes a buffer to hold the derived key; OUT: contains the derived key[inout] outDerivedKeyLen
: IN: length of theoutDerivedKey
buffer passed; OUT: the number of bytes returned inoutDerivedKey
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_BUF_TOO_SMALL
:outDerivedKey
is too small to return the derived keyHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_Encrypt
(HLSE_MECHANISM_INFO *pMechanismType, HLSE_OBJECT_HANDLE hObject, U8 *inData, U16 inDataLen, U8 *outData, U16 *outDataLen) Encrypts the data provided using the Object key and the requested mechanism.
The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter. A handle to the key to encrypt the data with is provided byhObject
.If additional information is required by the specific encryption mechanism, is will be conveyed in
pMechanismType->pParameter
.If
outData
is NULL, then all that the function does is return (in*outDataLen
) a number of bytes which would suffice to hold the return value. HLSE_SW_OK is returned by the function.If
outData
is not NULL, then*outDataLen
must contain the number of bytes in the bufferoutData
. If that buffer is large enough to hold the data be returned, then the data is copied tooutData
, 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,*outDataLen
is set to hold the exact number of bytes to be returned.- Parameters
[in] pMechanismType
: The encryption Cryptographic Mechanism to be used[in] hObject
: The handle of the Object key to encrypt with[in] inData
: Data buffer for that should be encrypted[in] inDataLen
: The length of data passed as argument[inout] outData
: IN: caller passes a buffer to hold the data to be returned; OUT: contains the encrypted data[inout] outDataLen
: IN: length of theoutData
buffer passed; OUT: the number of bytes returned inoutData
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_BUF_TOO_SMALL
:outData
is too small to return the dataHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_Decrypt
(HLSE_MECHANISM_INFO *pMechanismType, HLSE_OBJECT_HANDLE hObject, U8 *inData, U16 inDataLen, U8 *outData, U16 *outDataLen) Decrypts the data provided using the Object key and the requested mechanism.
The Cryptographic Mechanism to be used is passed in the
type
member of thepMechanismType
parameter. A handle to the key to decrypt the data with is provided byhObject
.If additional information is required by the specific decryption mechanism, is will be conveyed in
pMechanismType->pParameter
.If
outData
is NULL, then all that the function does is return (in*outDataLen
) a number of bytes which would suffice to hold the return value. HLSE_SW_OK is returned by the function.If
outData
is not NULL, then*outDataLen
must contain the number of bytes in the bufferoutData
. If that buffer is large enough to hold the data be returned, then the data is copied tooutData
, 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,*outDataLen
is set to hold the exact number of bytes to be returned.- Parameters
[in] pMechanismType
: The decryption Cryptographic Mechanism to be used[in] hObject
: The handle of the Object key to decrypt with[in] inData
: Data buffer for that should be decrypted[in] inDataLen
: The length of data passed as argument[inout] outData
: IN: caller passes a buffer to hold the data to be returned; OUT: contains the decrypted data[inout] outDataLen
: IN: length of theoutData
buffer passed; OUT: the number of bytes returned inoutData
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_BUF_TOO_SMALL
:outData
is too small to return the dataHLSE_ERR_API_ERROR
: Invalid function arguments
10.4.3.3. HLSEComm.h¶
- Description
Host Lib wrapper API: Communication and Secure Channel functions
Functions
-
HLSE_RET_CODE
HLSE_Connect
(HLSE_CONNECTION_PARAMS *params, HLSE_COMMUNICATION_STATE *commState) Establishes the communication with the Secure Element accroding to the requested
type
. Additional parameters required for establishing the communication are passed inparams
.The physical communication layer used (e.g. SCI2C) is determined at compilation time.
- Parameters
[inout] params
: Additional parameters for opening the commuication[inout] commState
: Points to a HLSE_COMMUNICATION_STATE which returns the communication state (e.g. ATR)
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_CloseConnection
(HLSE_CLOSE_CONNECTION_MODE mode) Closes the communication with the Secure Element.
- Parameters
[in] mode
: Specific information that may be required on the link layer
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_ResumeConnection
(HLSE_COMMUNICATION_STATE *commState, HLSE_SECURE_CHANNEL_SESSION_STATE *smState) Resumes the communication with the Secure Element including the secure channel from the previously retrieved communication state and secure channel session state.
- Parameters
[in] commState
: communication state[in] smState
: secure channel session state
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_SendAPDU
(U8 *cmd, U16 cmdLen, U8 *resp, U16 *respLen) Sends the command APDU to the Secure Element and retrieves the response APDU. The latter consists of the concatenation of the response data (possibly none) and the status word (2 bytes).
The command APDU and response APDU are not interpreted by the host library.
The command/response APDU sizes must lay within the APDU size limitations
- Parameters
[in] cmd
: command APDU[in] cmdLen
: length (in byte) ofcmd
[inout] resp
: response APDU (response data || response status word)[inout] respLen
: IN: Length of resp buffer (resp
) provided; OUT: effective length of response retrieved.
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_SCP_Subscribe
(HLSE_SCP_SignalFunction callback, void *context) Subscribe a HLSE_SCP_SignalFunction function to receive messages from the Secure Channel.
- Parameters
[in] callback
: The function[in] context
: Optional context information that the function is subsrcibed with and called with
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_SMChannelAuthenticate
(HLSE_SECURE_CHANNEL_ESTABLISH_PARAMS *params, HLSE_SECURE_CHANNEL_STATE *channelState) Establishes a Secure Channel with the Secure Element, and when successful initializes the current Session Channel state.
- Parameters
[in] params
: Data required to establish the Secure Channel[inout] channelState
: Returns the Secure Channel state
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_SMChannelGetScpSessionState
(HLSE_SECURE_CHANNEL_SESSION_STATE *channelSessionState) Retrieve the Secure Channel Session state from the Host Library.
- Parameters
[inout] channelSessionState
: IN: pointer to allocated structure; OUT: contains the session state
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_SMChannelSetScpSessionState
(HLSE_SECURE_CHANNEL_SESSION_STATE *channelSessionState) Sets the Secure Channel Session state of the Host Library. Can be used in a scenario where e.g. the bootloader has established the Secure Channel link between host and secure element and the Host OS must re-establish the communication with the secure element without breaking the session.
- Parameters
[in] channelSessionState
: Contains the session state information
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
10.4.3.4. HLSEMisc.h¶
- Description
Host Lib wrapper API: Miscellaneous functions
Functions
-
HLSE_RET_CODE
HLSE_DisablePlainInjectionMode
(void) Permanently disables the Plain Injection mode
- Return Value
HLSE_SW_OK
: Upon successful execution
-
HLSE_RET_CODE
HLSE_ResetContents
(void) Clears all user data.
- Return Value
HLSE_SW_OK
: Upon successful execution
-
HLSE_RET_CODE
HLSE_DbgDisableDebug
(void) Permanently disables the Debug API.
- Return Value
HLSE_SW_OK
: Upon successful execution
-
HLSE_RET_CODE
HLSE_DbgReflect
(U8 *inData, U16 inDataLen, U8 *outData, U16 *outDataLen) Invokes data reflection APDU (facilitates link testing). No check of data payload returned
- Parameters
[in] inData
: The data to be sent to the Secure Element[in] inDataLen
: The length ofinData
[inout] outData
: IN: caller passes a buffer to hold the data to be returned; OUT: contains the retruend data[inout] outDataLen
: IN: length of theoutData
buffer passed; OUT: the number of bytes returned inoutData
- Return Value
HLSE_SW_OK
: Upon successful executionHLSE_ERR_API_ERROR
: Invalid function arguments
-
HLSE_RET_CODE
HLSE_DbgReset
(void) Resets the Secure Module to the initial state.
- Return Value
HLSE_SW_OK
: Upon successful execution
-
HLSE_RET_CODE
HLSE_NormalizeECCSignature
(U8 *signature, U16 signatureLen, U8 *normalizedSignature, U16 *normalizedSignatureLen) The purpose of this function is to turn the proprietary ECDSA signature format - that may be returned by the applet - into a normalized ASN.1 format.
- Parameters
[in] signature
: buffer containing the ECDSA signature in the applet specific format; OUT: Signature compliant to ASN.1[in] signatureLen
: length of ECDSA signature length[inout] normalizedSignature
: IN: caller passes a buffer to hold the data to be returned; OUT: contains the retruend data[inout] normalizedSignatureLen
: IN: length of theoutData
buffer passed; OUT: the number of bytes returned inoutData
- Return Value
HLSE_SW_OK
: upon successfull executionHLSE_ERR_API_ERROR
: Invalid function arguments