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:

  1. HLSE_ATTR_OBJECT_TYPE ? currently HLSE_CERTIFICATE or HLSE_DATA;

  2. HLSE_ATTR_OBJECT_INDEX ? will be the Tag of the object, 1 byte;

  3. 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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 in objectsHandles.

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 buffer objectHandles. If that buffer is large enough to hold number of handles to be returned, then the handles are copied to 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, *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 execution

  • HLSE_ERR_BUF_TOO_SMALL: Buffer is too small to return the handles

  • HLSE_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 in attributes

  • [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 execution

  • HLSE_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 execution

  • HLSE_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 buffer attribute->value. If that buffer is large enough to hold the value be returned, then the data is copied to 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, *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 execution

  • HLSE_ERR_BUF_TOO_SMALL: attribute->value is too small to return the data

  • HLSE_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 buffer mechanisms. If that buffer is large enough to hold number of mechanisms to be returned, then the mechanisms are copied to mechanisms, 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 execution

  • HLSE_ERR_BUF_TOO_SMALL: Buffer is too small to return the mechanisms

  • HLSE_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 buffer mechanisms. If that buffer is large enough to hold number of mechanisms to be returned, then the mechanisms are copied to mechanisms, 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 execution

  • HLSE_ERR_BUF_TOO_SMALL: Buffer is too small to return the mechanisms

  • HLSE_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 the pMechanismType 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 buffer outDigest. If that buffer is large enough to hold the digest value be returned, then the data is copied to outDigest, 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 the outDigest buffer passed; OUT: the number of bytes returned in outDigest

Return Value
  • HLSE_SW_OK: Upon successful execution

  • HLSE_ERR_BUF_TOO_SMALL: outDigest is too small to return the digest

  • HLSE_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 the pMechanismType parameter. A handle to the key to sign the data with is provided by hObject.

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 buffer outSignature. If that buffer is large enough to hold the signature be returned, then the data is copied to outSignature, 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 the outSignature buffer passed; OUT: the number of bytes returned in outSignature

Return Value
  • HLSE_SW_OK: Upon successful execution

  • HLSE_ERR_BUF_TOO_SMALL: outSignature is too small to return the signature

  • HLSE_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 of inData using the public key object referenced by hObject as the verifying public key.

The Cryptographic Mechanism to be used is passed in the type member of the pMechanismType 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 execution

  • HLSE_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 of inData using an external public key object as the verifying public key.

The Cryptographic Mechanism to be used is passed in the type member of the pMechanismType 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 execution

  • HLSE_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 in outDerivedKey.

The Cryptographic Mechanism to be used is passed in the type member of the pMechanismType 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 buffer outDerivedKey. If that buffer is large enough to hold the derived key, then the data is copied to outDerivedKey, 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 the outDerivedKey buffer passed; OUT: the number of bytes returned in outDerivedKey

Return Value
  • HLSE_SW_OK: Upon successful execution

  • HLSE_ERR_BUF_TOO_SMALL: outDerivedKey is too small to return the derived key

  • HLSE_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 the pMechanismType parameter. A handle to the key to encrypt the data with is provided by hObject.

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 buffer outData. If that buffer is large enough to hold the data be returned, then the data is copied to outData, 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 the outData buffer passed; OUT: the number of bytes returned in outData

Return Value
  • HLSE_SW_OK: Upon successful execution

  • HLSE_ERR_BUF_TOO_SMALL: outData is too small to return the data

  • HLSE_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 the pMechanismType parameter. A handle to the key to decrypt the data with is provided by hObject.

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 buffer outData. If that buffer is large enough to hold the data be returned, then the data is copied to outData, 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 the outData buffer passed; OUT: the number of bytes returned in outData

Return Value
  • HLSE_SW_OK: Upon successful execution

  • HLSE_ERR_BUF_TOO_SMALL: outData is too small to return the data

  • HLSE_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 in params.

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 execution

  • HLSE_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 execution

  • HLSE_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 execution

  • HLSE_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) of cmd

  • [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 execution

  • HLSE_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 execution

  • HLSE_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 execution

  • HLSE_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 execution

  • HLSE_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 execution

  • HLSE_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 of inData

  • [inout] outData: IN: caller passes a buffer to hold the data to be returned; OUT: contains the retruend data

  • [inout] outDataLen: IN: length of the outData buffer passed; OUT: the number of bytes returned in outData

Return Value
  • HLSE_SW_OK: Upon successful execution

  • HLSE_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 the outData buffer passed; OUT: the number of bytes returned in outData

Return Value
  • HLSE_SW_OK: upon successfull execution

  • HLSE_ERR_API_ERROR: Invalid function arguments