/** * @file a71ch_api.h * @author NXP Semiconductors * @version 1.0 * @par License * * Copyright 2016,2020 NXP * SPDX-License-Identifier: Apache-2.0 * * @par Description * This file provides the public interface of the A71CH module. * @par History * 1.0 1-oct-2016 : Initial version * *****************************************************************************/ #ifndef _A71CH_API_ #define _A71CH_API_ #include "sm_types.h" #include "scp.h" #include "ax_common.h" #ifdef __cplusplus extern "C" { #endif /* ------------------------------ */ typedef U8 SST_Index_t; #define A71CH_INJECT_LOCK_STATE_LOCKED 0x01 //!< Locked #define A71CH_INJECT_LOCK_STATE_UNLOCKED 0x02 //!< Unlocked #define A71CH_TRANSPORT_LOCK_STATE_LOCKED 0x01 //!< Transport Lock set #define A71CH_TRANSPORT_LOCK_STATE_UNLOCKED 0x02 //!< Open device, Transport Lock can no longer be set #define A71CH_TRANSPORT_LOCK_STATE_ALLOW_LOCK 0x03 //!< Open device, Transport Lock can still be set #define A71CH_NO_RESTRICTED_KP 0x0F //!< No restricted keypairs available #define A71CH_KEY_PAIR_0 0x00 //!< Index to credential storage #define A71CH_KEY_PAIR_1 0x01 //!< Index to credential storage #define A71CH_KEY_PAIR_2 0x02 //!< Index to credential storage (B device only) #define A71CH_KEY_PAIR_3 0x03 //!< Index to credential storage (B device only) #define A71CH_PUBLIC_KEY_0 0x00 //!< Index to credential storage #define A71CH_PUBLIC_KEY_1 0x01 //!< Index to credential storage #define A71CH_PUBLIC_KEY_2 0x02 //!< Index to credential storage (B device only) #define A71CH_SYM_KEY_0 0x00 //!< Index to credential storage #define A71CH_SYM_KEY_1 0x01 //!< Index to credential storage #define A71CH_SYM_KEY_2 0x02 //!< Index to credential storage #define A71CH_SYM_KEY_3 0x03 //!< Index to credential storage #define A71CH_SYM_KEY_4 0x04 //!< Index to credential storage (B device only) #define A71CH_SYM_KEY_5 0x05 //!< Index to credential storage (B device only) #define A71CH_SYM_KEY_6 0x06 //!< Index to credential storage (B device only) #define A71CH_SYM_KEY_7 0x07 //!< Index to credential storage (B device only) #define A71CH_COUNTER_0 0x00 //!< Index to credential storage #define A71CH_COUNTER_1 0x01 //!< Index to credential storage #define A71CH_CFG_KEY_IDX_MODULE_LOCK 0x00 //!< Index of Module Transport Lock configuration key #define A71CH_CFG_KEY_IDX_PRIVATE_KEYS 0x01 //!< Index to configuration key storage (private key wrapping key) #define A71CH_CFG_KEY_IDX_PUBLIC_KEYS 0x02 //!< Index to configuration key storage (public key wrapping key) #define A71CH_SYM_KEY_COMBINED_MAX 4 //!< Maximum amount of 128 bit symmetric keys that can be combined for a crypto operation in A71CH #define A71CH_MAP_SIZE_MAX 203 //!< Maximum amount of data that can be retrieved with debug credential info // #define A71CH_OPERATE_MATRIX_SIZE 8 #define A71CH_MAX_CMD_PAYLOAD_SIZE 255 //!< Maximum size of command data #define A71CH_SCP03_MAX_PAYLOAD_SIZE 239 //!< Maximum size of command/response data in case SCP03 in enabled #define A71CH_GP_STORAGE_SIZE_A 1024 //!< The general purpose storage available on dev. version A71CH (Rev. < 1.3) #define A71CH_GP_STORAGE_SIZE_B 4096 //!< The general purpose storage available on the A71CH product #define A71CH_GP_STORAGE_GRANULARITY 32 //!< Determines the granularity with which GP storage blocks can be locked #define A71CH_GP_STORAGE_MAX_DATA_CHUNK (A71CH_SCP03_MAX_PAYLOAD_SIZE) //!< GP Storage specific implementation parameter #define DERIVE_KEYDATA_FROM_SHARED_SECRET_MAX_INFO 192 #define DERIVE_KEYDATA_FROM_SHARED_SECRET_MAX_DERIVED_DATA 255 #define A71CH_HKDF_MAX_SALT 32 #define A71CH_HMAC_SHA256_MAX_DATA_CHUNK (A71CH_SCP03_MAX_PAYLOAD_SIZE) //!< HMAC specific implementation parameter #define A71CH_SHA256_MAX_DATA_CHUNK (A71CH_SCP03_MAX_PAYLOAD_SIZE) //!< SHA256 specific implementation parameter #define A71CH_TLS_MAX_LABEL 24 //!< Maximum size of label that can be stored in A71CH #define A71CH_MODULE_UNLOCK_CHALLENGE_LEN 16 //!< Length (in byte) of challenge created by secure module to get it unlocked #define A71CH_MODULE_UNIQUE_ID_LEN 18 //!< Length (in byte) of unique identifier contained in secure module #define A71CH_MODULE_CERT_UID_LEN 10 //!< Length (in byte) of cert unique identifier #define A71CH_WRAPPED_KEY_LEN 24 //!< Length (in byte) of an RFC3394 wrapped AES key of 128 bits #define A71CH_PUB_KEY_LEN 65 //!< Length (in byte) of an ECC P-256 Public Key in ANSI X9.62 uncompressed format #define AX_SHA256_LEN 32 //!< Length (in byte) of the result of a SHA256 hash operation #define AX_TLS_PSK_MASTER_SECRET_LEN 48 //!< Length (in byte) of TLS 1.2 Master Secret #define AX_TLS_PSK_HELLO_RANDOM_LEN 32 //!< Length (in byte) of TLS 1.2 Hello #define SESSION_ID_LEN 4 #define MONOTONIC_COUNTER_BYTE_COUNT 4 //!< Length (in byte) of monotonic counter #define A71CH_SCP_MANDATORY 0x01 //!< After a successful GP_ExternalAuthenticate, the usage of SCP03 becomes MANDATORY #define A71CH_SCP_NOT_SET_UP 0x02 //!< No SCP keys written #define A71CH_SCP_KEYS_SET 0x03 //!< Successfully written SCP keys (with GP_PutKey), SCP03 binding has not yet been set up #define A71CH_SCP_CHANNEL_STATE_UNKNOWN 0x0F //!< SCP channel state not known /// @cond #define A71CH_UID_IC_TYPE_OFFSET 2 #define A71CH_UID_IC_FABRICATION_DATA_OFFSET 8 #define A71CH_UID_IC_SERIAL_NR_OFFSET 10 #define A71CH_UID_IC_BATCH_ID_OFFSET 13 /// @endcond /* ------------------------------ */ /** \name Module functions @{ */ U16 A71_GetCredentialInfo(U8 *map, U16 *mapLen); U16 A71_GetModuleInfo(U16 *selectResponse, U8 *debugOn, U8 *restrictedKpIdx, U8 *transportLockState, U8 *scpState, U8 *injectLockState, U16 *gpStorageSize); U16 A71_GetRandom(U8 *random, U8 randomLen); U16 A71_CreateClientHelloRandom(U8 *clientHello, U8 clientHelloLen); U16 A71_GetRestrictedKeyPairInfo(U8 *idx, U16 *nBlocks, U8 *blockInfo, U16 *blockInfoLen); U16 A71_GetSha256(U8 *data, U16 dataLen, U8 *sha, U16 *shaLen); U16 A71_Sha256Init(void); U16 A71_Sha256Update(U8 *data, U16 dataLen); U16 A71_Sha256Final(U8 *sha, U16 *shaLen); U16 A71_GetUniqueID(U8 *uid, U16 *uidLen); U16 A71_GetCertUid(U8 *certUid, U16 *certUidLen); U16 A71_GetKeyPairChallenge(U8 *challenge, U16 *challengeLen); U16 A71_GetPublicKeyChallenge(U8 *challenge, U16 *challengeLen); U16 A71_GetUnlockChallenge(U8 *challenge, U16 *challengeLen); U16 A71_InjectLock(void); U16 A71_LockModule(void); U16 A71_UnlockModule(U8 *code, U16 codeLen); U16 A71_SetTlsLabel(const U8* label, U16 labelLen); U16 A71_EccVerifyWithKey(const U8 *pKeyData, U16 keyDataLen, const U8 *pHash, U16 hashLen, const U8 *pSignature, U16 signatureLen, U8 *pResult); /** @}*/ /** \name EccKeyPair functions @{ */ U16 A71_GenerateEccKeyPair(SST_Index_t index); U16 A71_GenerateEccKeyPairWithChallenge(SST_Index_t index, const U8 *configKey, U16 configKeyLen); U16 A71_GenerateEccKeyPairWithCode(SST_Index_t index, const U8 *code, U16 codeLen); U16 A71_SetEccKeyPair(SST_Index_t index, const U8 *publicKey, U16 publicKeyLen, const U8 *privateKey, U16 privateKeyLen); U16 A71_GetPublicKeyEccKeyPair(SST_Index_t index, U8 *publicKey, U16 *publicKeyLen); U16 A71_GetEccKeyPairUsage(SST_Index_t index, U8 *restricted, U16 *usedCnt, U16 *maxUseCnt); U16 A71_EccSign(SST_Index_t index, const U8 *pHash, U16 hashLen, U8 *pSignature, U16 *pSignatureLen); U16 A71_EccNormalizedAsnSign(SST_Index_t index, const U8 *pHash, U16 hashLen, U8 *pSignature, U16 *pSignatureLen); U16 A71_EccRestrictedSign(SST_Index_t index, const U8 *updateBytes, U16 updateBytesLen, U8 *invocationCount); U16 A71_EcdhGetSharedSecret(U8 index, const U8 *pOtherPublicKey, U16 otherPublicKeyLen, U8 *pSharedSecret, U16 *pSharedSecretLen); U16 A71_FreezeEccKeyPair(SST_Index_t index); U16 A71_FreezeEccKeyPairWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen); U16 A71_FreezeEccKeyPairWithCode(SST_Index_t index, U8 *code, U16 codeLen); U16 A71_EraseEccKeyPair(SST_Index_t index); U16 A71_EraseEccKeyPairWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen); U16 A71_EraseEccKeyPairWithCode(SST_Index_t index, U8 *code, U16 codeLen); /** @}*/ /** \name EccPublicKey functions @{ */ U16 A71_SetEccPublicKey(SST_Index_t index, const U8 *publicKey, U16 publicKeyLen); U16 A71_GetEccPublicKey(SST_Index_t index, U8 *publicKey, U16 *publicKeyLen); U16 A71_FreezeEccPublicKey(SST_Index_t index); U16 A71_FreezeEccPublicKeyWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen); U16 A71_FreezeEccPublicKeyWithCode(SST_Index_t index, U8 *code, U16 codeLen); U16 A71_EraseEccPublicKey(SST_Index_t index); U16 A71_EraseEccPublicKeyWithChallenge(SST_Index_t index, U8 *configKey, U16 configKeyLen); U16 A71_EraseEccPublicKeyWithCode(SST_Index_t index, U8 *code, U16 codeLen); U16 A71_EccVerify(SST_Index_t index, const U8 *pHash, U16 hashLen, const U8 *pSignature, U16 signatureLen, U8 *pResult); /** @}*/ /** \name Symmetric key functions @{ */ U16 A71_SetSymKey(SST_Index_t index, const U8 *key, U16 keyLen); U16 A71_SetRfc3394WrappedAesKey(SST_Index_t index, const U8 *key, U16 keyLen); U16 A71_FreezeSymKey(SST_Index_t index); U16 A71_EraseSymKey(SST_Index_t index); U16 A71_GetHmacSha256(SST_Index_t index, U8 nBlock, const U8 *data, U16 dataLen, U8 *hmac, U16 *hmacLen); U16 A71_HmacSha256Init(SST_Index_t index, U8 nBlock); U16 A71_HmacSha256Update(SST_Index_t index, U8 nBlock, U8 *data, U16 dataLen); U16 A71_HmacSha256Final(SST_Index_t index, U8 nBlock, U8 *hmac, U16 *hmacLen); U16 A71_HkdfExpandSymKey(SST_Index_t index, U8 nBlock, const U8 *info, U16 infoLen, U8 *derivedData, U16 derivedDataLen); U16 A71_HkdfSymKey(SST_Index_t index, U8 nBlock, const U8 *salt, U16 saltLen, const U8 *info, U16 infoLen, U8 *derivedData, U16 derivedDataLen); U16 A71_PskDeriveMasterSecret(SST_Index_t index, U8 nBlock, const U8 *serverHelloRnd, U16 serverHelloRndLen, U8 *masterSecret); /** @}*/ /** \name General purpose storage functions @{ */ U16 A71_SetGpData(U16 dataOffset, const U8 *data, U16 dataLen); U16 A71_SetGpDataWithLockCheck(U16 dataOffset, const U8 *data, U16 dataLen); U16 A71_GetGpData(U16 dataOffset, U8 *data, U16 dataLen); U16 A71_FreezeGpData(U16 dataOffset, U16 dataLen); /** @}*/ /** \name Monotonic Counter functions @{ */ U16 A71_IncrementCounter(SST_Index_t index); U16 A71_SetCounter(SST_Index_t index, U32 value); U16 A71_GetCounter(SST_Index_t index, U32 *pValue); /** @}*/ /** \name Crypto functions referring to multiple stored credentials @{ */ U16 A71_EcdhPskDeriveMasterSecret(SST_Index_t indexKp, const U8 *publicKey, U16 publicKeyLen, SST_Index_t index, U8 nBlock, const U8 *serverHelloRnd, U16 serverHelloRndLen, U8 *masterSecret); /** @}*/ /** \name Config key functions @{ */ U16 A71_SetConfigKey(SST_Index_t index, const U8 *Key, U16 keyLen); U16 A71_SetRfc3394WrappedConfigKey(SST_Index_t index, const U8 *Key, U16 keyLen); /** @}*/ // The Link Layer used to communicate between Host and Secure Element may introduce // additional constraints on the packetsize. This constraint is set by defining MAX_CHUNK_LENGTH_LINK. // NOTE: In sm_apdu.h MAX_APDU_BUF_LENGTH is set. This value corresponds to the maximum APDU // buffer length of the Security Module. // On memory constrained hosts these values can be reduced to a lower value. // #define MAX_CHUNK_LENGTH_LINK 1024 // Compromise value; can be reduced to about 650 // The A71CH has been tested in combination with: SCI2C interface & SMCOM_JRCP_V1 // TODO: Have the MAX_APDU_BUF_LENGTH take precedence on MAX_CHUNK_LENGTH_LINK // for the time being the cap on the APDU size is enforced through MAX_CHUNK_LENGTH_LINK #if defined(SCI2C) || defined (T1oI2C) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #elif defined(SPI) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #elif defined(PCSC) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #elif defined(TDA8029_UART) #error "Not yet tested" #elif defined(SMCOM_JRCP_V1) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #elif defined(SMCOM_JRCP_V2) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #elif defined(IPC) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #elif defined(RJCT_VCOM) || defined(SMCOM_JRCP_V1) || defined(SMCOM_JRCP_V2) || defined(SMCOM_PN7150) || defined(SMCOM_THREAD) || defined(SMCOM_PCSC) || defined(SMCOM_RC663_VCOM) #define MAX_CHUNK_LENGTH_LINK 256 //!< Limited by A71CH applet capability #else #error "Define a communication layer as a preprocessor constant" #endif #ifdef __cplusplus } #endif #endif //_A71CH_API_