| /* |
| * @author NXP Semiconductors |
| * @version 1.0 |
| * @par License |
| * |
| * Copyright 2017,2020 NXP |
| * SPDX-License-Identifier: Apache-2.0 |
| * |
| * |
| * @par HISTORY |
| * |
| */ |
| /** |
| * @file HLSECrypto.h |
| * @par Description |
| * Host Lib wrapper API: Cryptographic functions |
| */ |
| #ifndef _HLSE_CRYPTO_H_ |
| #define _HLSE_CRYPTO_H_ |
| |
| #include "HLSETypes.h" |
| |
| // HLSE stands for: Host Library Secure Element |
| |
| |
| /** |
| * Enumerates all the Cryptographic Mechanisms that are supported by the library. A list of mechanisms is returned in \p mechanisms. |
| |
| If \p mechanisms is NULL, then all that the function does is return (in \p *mechanismNum) the number of HLSE_MECHANISM_TYPE which would suffice |
| to hold the returned list. HLSE_SW_OK is returned by the function. |
| |
| If \p mechanisms is not NULL, then \p *mechanismNum must contain the number of mechanisms in the buffer \p mechanisms. If that buffer |
| is large enough to hold number of mechanisms to be returned, then the mechanisms are copied to \p 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, \p *mechanismNum is set to hold the exact number of |
| mechanisms to be returned. |
| |
| * \param[in, out] mechanisms IN: caller passes a buffer of at least *mechanismNum; OUT: contains the mechanisms supported |
| * \param[in, out] mechanismNum IN: number of mechanisms in mechanisms; OUT: set to hold the exact number of mechanisms |
| * |
| * \retval ::HLSE_SW_OK Successfull execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL Buffer is too small to return the mechanisms |
| * \retval ::HLSE_ERR_API_ERROR Invalid function arguments |
| */ |
| HLSE_RET_CODE HLSE_GetSupportedMechanisms(HLSE_MECHANISM_TYPE* mechanisms, U16* mechanismNum); |
| |
| /** |
| * Enumerates all the Cryptographic Mechanisms that are supported by the Object. A list of mechanisms is returned in \p mechanisms. |
| |
| If \p mechanism is NULL, then all that the function does is return (in \p *mechanismLen) the number of HLSE_MECHANISM_TYPE which would suffice |
| to hold the returned list. HLSE_SW_OK is returned by the function. |
| |
| If \p mechanism is not NULL, then \p *mechanismLen must contain the number of mechanisms in the buffer \p mechanisms. If that buffer |
| is large enough to hold number of mechanisms to be returned, then the mechanisms are copied to \p 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, \p *mechanismLen is set to hold the exact number of |
| mechanisms to be returned. |
| |
| * \param[in] hObject The handle of the Object that the Mechanisms it supports should be returned |
| * \param[in, out] mechanism IN: caller passes a buffer of at least *mechanismNum; OUT: contains the mechanisms supported |
| * \param[in, out] mechanismLen IN: number of mechanisms in mechanisms. OUT: set to hold the exact number of mechanisms |
| * |
| * \retval ::HLSE_SW_OK Successfull execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL Buffer is too small to return the mechanisms |
| * \retval ::HLSE_ERR_API_ERROR Invalid function arguments |
| */ |
| HLSE_RET_CODE HLSE_GetSupportedMechanismsForObject(HLSE_OBJECT_HANDLE hObject, HLSE_MECHANISM_TYPE* mechanism, U16* mechanismLen); |
| |
| /** |
| * Calculates the Digest (e.g. Sha256) value of the data provided as input. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| |
| If additional information is required by the specific digest mechanism, is will be conveyed in \p pMechanismType->pParameter. |
| |
| If \p outDigest is NULL, then all that the function does is return (in \p *outDigestLen) a number of bytes which would suffice |
| to hold the digest value. HLSE_SW_OK is returned by the function. |
| |
| If \p outDigest is not NULL, then \p *outDigestLen must contain the number of bytes in the buffer \p outDigest. If that buffer |
| is large enough to hold the digest value be returned, then the data is copied to \p 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, \p *outDigestLen is set to hold the exact number of |
| bytes to be returned. |
| |
| * \param[in] pMechanismType The Digest Cryptographic Mechanism to be used |
| * \param[in] inData Data buffer for which the digest must be calculated |
| * \param[in] inDataLen The length of data passed as argument |
| * \param[in,out] outDigest IN: caller passes a buffer to hold the digest value; |
| OUT: contains the calculated digest |
| * \param[in,out] outDigestLen IN: length of the \p outDigest buffer passed; |
| OUT: the number of bytes returned in \p outDigest |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL \p outDigest is too small to return the digest |
| * \retval ::HLSE_ERR_API_ERROR Invalid function arguments |
| */ |
| HLSE_RET_CODE HLSE_Digest(HLSE_MECHANISM_INFO* pMechanismType, |
| U8* inData, U16 inDataLen, |
| U8* outDigest, U16* outDigestLen); |
| |
| /** |
| * Signs the data provided using the Object key and the requested mechanism. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| A handle to the key to sign the data with is provided by \p hObject. |
| |
| If additional information is required by the specific signing mechanism, is will be conveyed in \p pMechanismType->pParameter. |
| |
| If \p outSignature is NULL, then all that the function does is return (in \p *outSignatureLen) a number of bytes which would suffice |
| to hold the signature. HLSE_SW_OK is returned by the function. |
| |
| If \p outSignature is not NULL, then \p *outSignatureLen must contain the number of bytes in the buffer \p outSignature. If that buffer |
| is large enough to hold the signature be returned, then the data is copied to \p 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, \p *outSignatureLen is set to hold the exact number of |
| bytes to be returned. |
| |
| * \param[in] pMechanismType The signing Cryptographic Mechanism to be used |
| * \param[in] hObject The handle of the Object key to sign with |
| * \param[in] inData Data buffer for that should be signed (e.g. a digest) |
| * \param[in] inDataLen The length of data passed as argument |
| * \param[in,out] outSignature IN: caller passes a buffer to hold the signature; |
| OUT: contains the calculated signature |
| * \param[in,out] outSignatureLen IN: length of the \p outSignature buffer passed; |
| OUT: the number of bytes returned in \p outSignature |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL \p outSignature is too small to return the signature |
| * \retval ::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); |
| |
| |
| /** |
| * Verifies whether \p inSignature is the signature of \p inData |
| using the public key object referenced by \p hObject as the verifying public key. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| |
| * \param[in] pMechanismType The signing Cryptographic Mechanism that was used |
| * \param[in] hObject The handle of the Object public key to verify with |
| * \param[in] inData The data that was signed (e.g. a digest) |
| * \param[in] inDataLen The length of data passed as argument |
| * \param[in] inSignature Pointer to the provided signature. |
| * \param[in] inSignatureLen Length of the provided signature (\p pSignature) |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::HLSE_ERR_GENERAL_ERROR if the verification fails |
| */ |
| HLSE_RET_CODE HLSE_VerifySignature(HLSE_MECHANISM_INFO* pMechanismType, HLSE_OBJECT_HANDLE hObject, |
| U8* inData, U16 inDataLen, |
| U8* inSignature, U16 inSignatureLen); |
| |
| /** |
| * Verifies whether \p inSignature is the signature of \p inData |
| using an external public key object as the verifying public key. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| |
| * \param[in] pMechanismType The signing Cryptographic Mechanism that was used |
| * \param[in] inExtKey The value of the external public key to verify with |
| * \param[in] inExtKeyLen The length in bytes of the external key |
| * \param[in] inData The data that was signed (e.g. a digest) |
| * \param[in] inDataLen The length of data passed as argument |
| * \param[in] inSignature Pointer to the provided signature. |
| * \param[in] inSignatureLen Length of the provided signature (\p pSignature) |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::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); |
| |
| /** |
| * Derives the key referenced by the \p hObject handle using the requested mechanism and return |
| the derived key in \p outDerivedKey. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| |
| If additional information is required by the specific signing mechanism, is will be conveyed in \p pMechanismType->pParameter. |
| |
| If \p outDerivedKey is NULL, then all that the function does is return (in \p *outDerivedKeyLen) a number of bytes which would suffice |
| to hold the derived key. HLSE_SW_OK is returned by the function. |
| |
| If \p outDerivedKey is not NULL, then \p *outDerivedKeyLen must contain the number of bytes in the buffer \p outDerivedKey. If that buffer |
| is large enough to hold the derived key, then the data is copied to \p 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, \p *outDerivedKeyLen is set to hold the exact number of |
| bytes of the derived key. |
| |
| * \param[in] pMechanismType The signing Cryptographic Mechanism to be used |
| * \param[in] hObject The handle of the Object key to be derived |
| * \param[in,out] outDerivedKey IN: caller passes a buffer to hold the derived key; |
| OUT: contains the derived key |
| * \param[in,out] outDerivedKeyLen IN: length of the \p outDerivedKey buffer passed; |
| OUT: the number of bytes returned in \p outDerivedKey |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL \p outDerivedKey is too small to return the derived key |
| * \retval ::HLSE_ERR_API_ERROR Invalid function arguments |
| */ |
| HLSE_RET_CODE HLSE_DeriveKey(HLSE_MECHANISM_INFO* pMechanismType, HLSE_OBJECT_HANDLE hObject, |
| U8* outDerivedKey, U16* outDerivedKeyLen); |
| |
| /** |
| * Encrypts the data provided using the Object key and the requested mechanism. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| A handle to the key to encrypt the data with is provided by \p hObject. |
| |
| If additional information is required by the specific encryption mechanism, is will be conveyed in \p pMechanismType->pParameter. |
| |
| If \p outData is NULL, then all that the function does is return (in \p *outDataLen) a number of bytes which would suffice |
| to hold the return value. HLSE_SW_OK is returned by the function. |
| |
| If \p outData is not NULL, then \p *outDataLen must contain the number of bytes in the buffer \p outData. If that buffer |
| is large enough to hold the data be returned, then the data is copied to \p 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, \p *outDataLen is set to hold the exact number of |
| bytes to be returned. |
| |
| * \param[in] pMechanismType The encryption Cryptographic Mechanism to be used |
| * \param[in] hObject The handle of the Object key to encrypt with |
| * \param[in] inData Data buffer for that should be encrypted |
| * \param[in] inDataLen The length of data passed as argument |
| * \param[in,out] outData IN: caller passes a buffer to hold the data to be returned; |
| OUT: contains the encrypted data |
| * \param[in,out] outDataLen IN: length of the \p outData buffer passed; |
| OUT: the number of bytes returned in \p outData |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL \p outData is too small to return the data |
| * \retval ::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); |
| |
| /** |
| * Decrypts the data provided using the Object key and the requested mechanism. |
| |
| The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter. |
| A handle to the key to decrypt the data with is provided by \p hObject. |
| |
| If additional information is required by the specific decryption mechanism, is will be conveyed in \p pMechanismType->pParameter. |
| |
| If \p outData is NULL, then all that the function does is return (in \p *outDataLen) a number of bytes which would suffice |
| to hold the return value. HLSE_SW_OK is returned by the function. |
| |
| If \p outData is not NULL, then \p *outDataLen must contain the number of bytes in the buffer \p outData. If that buffer |
| is large enough to hold the data be returned, then the data is copied to \p 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, \p *outDataLen is set to hold the exact number of |
| bytes to be returned. |
| |
| * \param[in] pMechanismType The decryption Cryptographic Mechanism to be used |
| * \param[in] hObject The handle of the Object key to decrypt with |
| * \param[in] inData Data buffer for that should be decrypted |
| * \param[in] inDataLen The length of data passed as argument |
| * \param[in,out] outData IN: caller passes a buffer to hold the data to be returned; |
| OUT: contains the decrypted data |
| * \param[in,out] outDataLen IN: length of the \p outData buffer passed; |
| OUT: the number of bytes returned in \p outData |
| * |
| * \retval ::HLSE_SW_OK Upon successful execution |
| * \retval ::HLSE_ERR_BUF_TOO_SMALL \p outData is too small to return the data |
| * \retval ::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); |
| |
| |
| #endif // _HLSE_CRYPTO_H_ |