/**
 * @file HostCryptoAPI.h
 * @author NXP Semiconductors
 * @version 1.0
 * @par License
 *
 * Copyright 2017 NXP
 * SPDX-License-Identifier: Apache-2.0
 *
 * @par Description
 * Host Crypto wrapper API for the A7-series security IC's
 *
 * @par HISTORY
 *
 */

#ifndef _HOST_CRYPTO_API_H_
#define _HOST_CRYPTO_API_H_

#include "HLSETypes.h"


#define HOST_CRYPTO_NOT_SUPPORTED -1  //!< Crypto engine does not support implementation
#define HOST_CRYPTO_ERROR          0  //!< Failure
#define HOST_CRYPTO_OK             1  //!< Success


/**
* Enumerates all the Cryptographic Mechanisms that are supported. A list of mechanisms is returned in \p mechanisms.

If \p mechanism 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 mechanism is not NULL, then \p *mechanismLen must contain the number of mechanisms in the buffer \p mechanism.  If that buffer
is large enough to hold number of mechanisms to be returned, then the mechanisms are copied to \p mechanism, 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, 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   HLCRYPT_GetSupportedMechanisms(HLSE_MECHANISM_TYPE* mechanism, U32* mechanismLen);


/**
* Encrypts the data provided using the given key and the requested mechanism.

The Cryptographic Mechanism to be used is passed in the \p type member of the \p pMechanismType parameter.
The key to encrypt the data with is provided by \p inKey.

If additional information is required by the specific encryption mechanism, is will be conveyed in \p pMechanismType->pParameter.

If \p outEncryptedData is NULL, then all that the function does is return (in \p *outEncryptedDataLen) a number of bytes which would suffice
to hold the return value.  HLSE_SW_OK is returned by the function.

If \p outEncryptedData is not NULL, then \p *outEncryptedDataLen must contain the number of bytes in the buffer \p outEncryptedData.  If that buffer
is large enough to hold the data be returned, then the data is copied to \p outEncryptedData, 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 *outEncryptedDataLen is set to hold the exact number of
bytes to be returned.

* \param[in] pMechanismType The encryption Cryptographic Mechanism to be used
* \param[in] inKey The key data to encrypt with
* \param[in] inKeyLen The length in bytes of \p inKey
* \param[in] inData    Data buffer for that should be encrypted
* \param[in] inDataLen The length of data passed as argument
* \param[in,out] outEncryptedData    IN: caller passes a buffer to hold the data to be returned;
OUT: contains the encrypted data
* \param[in,out] outEncryptedDataLen IN: length of the \p outEncryptedData buffer passed;
OUT: the number of bytes returned in \p outEncryptedData
*
* \retval ::HLSE_SW_OK Upon successful execution
* \retval ::HLSE_ERR_BUF_TOO_SMALL \p outEncryptedData is too small to return the data
* \retval ::HLSE_ERR_API_ERROR Invalid function arguments
*/
HLSE_RET_CODE   HLCRYPT_Encrypt(HLSE_MECHANISM_INFO* pMechanismType, U8* inKey, U32 inKeyLen,
                                U8* inData, U32 inDataLen,
                                U8* outEncryptedData, U32* outEncryptedDataLen);

/**
* Decrypts the data provided using the given 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 outDecryptedData is NULL, then all that the function does is return (in \p *outDecryptedDataLen) 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 *outDecryptedDataLen must contain the number of bytes in the buffer \p outDecryptedData.  If that buffer
is large enough to hold the data be returned, then the data is copied to \p outDecryptedData, 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 *outDecryptedDataLen is set to hold the exact number of
bytes to be returned.

* \param[in] pMechanismType The decryption Cryptographic Mechanism to be used
* \param[in] inKey The key data to decrypt with
* \param[in] inKeyLen The length in bytes of \p inKey
* \param[in] inData    Data buffer for that should be decrypted
* \param[in] inDataLen The length of data passed as argument
* \param[in,out] outDecryptedData    IN: caller passes a buffer to hold the data to be returned;
OUT: contains the decrypted data
* \param[in,out] outDecryptedDataLen IN: length of the \p outDecryptedData buffer passed;
OUT: the number of bytes returned in \p outDecryptedData
*
* \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   HLCRYPT_Decrypt(HLSE_MECHANISM_INFO* pMechanismType, U8* inKey, U32 inKeyLen,
                                U8* inData, U32 inDataLen,
                                U8* outDecryptedData, U32* outDecryptedDataLen);

/**
* 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   HLCRYPT_Digest(HLSE_MECHANISM_INFO* pMechanismType,
                            U8* inData, U32 inDataLen,
                            U8* outDigest, U32* outDigestLen);


/**
* Signs the data provided using the given 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] inKey The key data to sign with
* \param[in] inKeyLen The length in bytes of \p inKey
* \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
* \retval ::HLSE_ERR_CRYPTO_ENGINE_FAILED in case of failure
*/
HLSE_RET_CODE   HLCRYPT_Sign(HLSE_MECHANISM_INFO* pMechanismType, U8* inKey, U32 inKeyLen,
                            U8* inData, U32 inDataLen,
                            U8* outSignature, U32* outSignatureLen);

/**
* Verifies the data provided using the given 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 verify the data with is provided by \p hObject.

If additional information is required by the specific verifying mechanism, is will be conveyed in \p pMechanismType->pParameter.

* \param[in] pMechanismType The verifying Cryptographic Mechanism to be used
* \param[in] inKey The key data to verify with
* \param[in] inKeyLen The length in bytes of \p inKey
* \param[in] inData    The mesage hash
* \param[in] inDataLen The length of hash
* \param[in] inSignature    IN: caller passes a buffer with signature to read and verify;
* \param[in] inSignatureLen IN: length of the \p inSignature buffer passed;
*
* \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
* \retval ::HLSE_ERR_CRYPTO_ENGINE_FAILED in case of failure
*/
HLSE_RET_CODE   HLCRYPT_Verify(HLSE_MECHANISM_INFO* pMechanismType, U8* inKey, U32 inKeyLen,
                            U8* inData, U32 inDataLen,
                            U8* inSignature, U32 inSignatureLen);

/**
* Initialize a Signature operation using the given 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.

* \param[in] pMechanismType The signing Cryptographic Mechanism to be used
* \param[in] inKey The key data to sign with
* \param[in] inKeyLen The length in bytes of \p inKey
* \param[out] hContext Pointer to context (double indirection)
*
* \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   HLCRYPT_SignInit(HLSE_MECHANISM_INFO* pMechanismType, U8* inKey, U32 inKeyLen, HLSE_CONTEXT_HANDLE* hContext);

/**
* Update/Append to data to be signed.

* \param[in] hContext The Context handle
* \param[in] inDataPart    Data buffer for that should be signed (e.g. a digest)
* \param[in] inDataPartLen The length of data passed as argument
*
* \retval ::HOST_CRYPTO_OK
* \retval ::HOST_CRYPTO_ERROR
*/
HLSE_RET_CODE   HLCRYPT_SignUpdate(HLSE_CONTEXT_HANDLE hContext, U8* inDataPart, U32 inDataPartLen);

/**
* Retrieves the Signature and clean up/free the context handle.

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]  hContext The Context handle
* \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
* \retval ::HOST_CRYPTO_OK
* \retval ::HOST_CRYPTO_ERROR
*/
HLSE_RET_CODE   HLCRYPT_SignFinal(HLSE_CONTEXT_HANDLE hContext, U8* outSignature, U32* outSignatureLen);

/**
* Fill up the provided buffer \p pRandomData with \p inLen byte of random data
* \param[in]     inLen    number (in bytes) of random data requested
* \param[in,out] pRandom  IN: buffer of at least inLen size; OUT: retrieved random data
*
* \retval ::HOST_CRYPTO_OK      Success
* \retval ::HOST_CRYPTO_ERROR   Random not supported by Crypto Engine
* \retval ::RET_SUCCESS
* \retval ::RET_FAILURE
* \retval ::RET_INSUFFICIENT_BUFFER_SIZE
*/
HLSE_RET_CODE    HLCRYPT_GetRandom(U32 inLen, U8 * pRandom);

/**
* Encrypts the data provided using the given key using single Des CBC mechanism.

If \p outData is NULL, then all that the function does is return (in \p *outEncryptedDataLen) 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] Key The key data to encrypt with
* \param[in] KeyLen The length in bytes of \p inKey
* \param[in] iv ICV to be used by CBC mechanism
* \param[in] ivlen The length in bytes of \p iv
* \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 outEncryptedData buffer passed;
OUT: the number of bytes returned in \p outEncryptedData
*
* \retval ::HLSE_SW_OK Upon successful execution
* \retval ::HLSE_ERR_BUF_TOO_SMALL \p outEncryptedData is too small to return the data
* \retval ::HLSE_ERR_API_ERROR Invalid function arguments
*/
HLSE_RET_CODE HLCRYPT_Single_DES_CBC_Encrypt(U8 *key, U32 keylen,
             U8 *iv,
             U16 ivlen,
             U8 *inData,
             U32 inDatalen,
             U8 * outData,
             U32 *outDatalen);
#endif