/** * @file tlcTeeKeymaster_if.h * @brief Contains TEE Keymaster trustlet connector interface definitions * * Copyright Giesecke & Devrient GmbH 2012 * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. The name of the author may not be used to endorse or promote * products derived from this software without specific prior * written permission. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef __TLCTEEKEYMASTERIF_H__ #define __TLCTEEKEYMASTERIF_H__ #ifdef __cplusplus extern "C" { #endif #include #include /** * Key sizes */ #define TEE_RSA_KEY_SIZE_512 512 #define TEE_RSA_KEY_SIZE_1024 1024 #define TEE_RSA_KEY_SIZE_2048 2048 /* error codes */ typedef enum { TEE_ERR_NONE = 0, TEE_ERR_FAIL = 1, TEE_ERR_INVALID_BUFFER = 2, TEE_ERR_BUFFER_TOO_SMALL = 3, TEE_ERR_NOT_IMPLEMENTED = 4, TEE_ERR_SESSION = 5, TEE_ERR_MC_DEVICE = 6, TEE_ERR_NOTIFICATION = 7, TEE_ERR_MEMORY = 8, TEE_ERR_MAP = 9 /* more can be added as required */ } teeResult_t; /* RSA key pair types */ typedef enum { TEE_KEYPAIR_RSA = 1, /**< RSA public and RSA private key. */ TEE_KEYPAIR_RSACRT = 2 /**< RSA public and RSA CRT private key. */ } teeRsaKeyPairType_t; /* Supported RSA signature algorithms */ typedef enum { /* RSA */ TEE_RSA_SHA_ISO9796 = 1, /**< 20-byte SHA-1 digest, padded according to the ISO 9796-2 scheme as specified in EMV '96 and EMV 2000, encrypted using RSA. */ TEE_RSA_SHA_ISO9796_MR = 2, /**< 20-byte SHA-1 digest, padded according to the ISO9796-2 specification and encrypted using RSA. */ TEE_RSA_SHA_PKCS1 = 3, /**< 20-byte SHA-1 digest, padded according to the PKCS#1 (v1.5) scheme, and encrypted using RSA. */ TEE_RSA_SHA256_PSS = 4, /**< SHA-256 digest and PSS padding */ TEE_RSA_SHA1_PSS = 5, /**< SHA-256 digest and PSS padding */ TEE_RSA_NODIGEST_NOPADDING = 6, /**< No digest and padding */ } teeRsaSigAlg_t; /* Digest types */ typedef enum { TEE_DIGEST_SHA1, TEE_DIGEST_SHA256 } teeDigest_t; /** * RSA private key metadata (Private modulus and exponent lengths) */ typedef struct { uint32_t lenprimod; /**< Private key modulus length */ uint32_t lenpriexp; /**< Private key exponent length */ } teeRsaPrivKeyMeta_t; /** * RSA CRT private key metadata (Private modulus and exponent lengths) */ typedef struct { uint32_t lenprimod; /**< Private key modulus length */ uint32_t lenp; /**< Prime p length */ uint32_t lenq; /**< Prime q length */ uint32_t lendp; /**< DP length */ uint32_t lendq; /**< DQ length */ uint32_t lenqinv; /**< QP length */ } teeRsaCrtPrivKeyMeta_t; /** * Key metadata (public key hash, key size, modulus/exponent lengths, etc..) */ typedef struct { uint32_t keytype; /**< Key type, e.g. RSA */ uint32_t keysize; /**< Key size, e.g. 1024, 2048 */ uint32_t lenpubmod; /**< Public key modulus length */ uint32_t lenpubexp; /**< Public key exponent length */ union { teeRsaPrivKeyMeta_t rsapriv; /**< RSA private key */ teeRsaCrtPrivKeyMeta_t rsacrtpriv; /**< RSA CRT private key */ }; uint32_t rfu; /**< Reserved for future use */ uint32_t rfulen; /**< Reserved for future use */ } teeRsaKeyMeta_t; /** * TEE_RSAGenerateKeyPair * * Generates RSA key pair and returns key pair data as wrapped object * * @param keyType [in] Key pair type. RSA or RSACRT * @param keyData [in] Pointer to the key data buffer * @param keyDataLength [in] Key data buffer length * @param keySize [in] Key size * @param exponent [in] Exponent number * @param soLen [out] Key data secure object length */ teeResult_t TEE_RSAGenerateKeyPair( teeRsaKeyPairType_t keyType, uint8_t* keyData, uint32_t keyDataLength, uint32_t keySize, uint32_t exponent, uint32_t* soLen); /** * TEE_RSASign * * Signs given plain data and returns signature data * * @param keyData [in] Pointer to key data buffer * @param keyDataLength [in] Key data buffer length * @param plainData [in] Pointer to plain data to be signed * @param plainDataLength [in] Plain data length * @param signatureData [out] Pointer to signature data * @param signatureDataLength [out] Signature data length * @param algorithm [in] RSA signature algorithm */ teeResult_t TEE_RSASign( const uint8_t* keyData, const uint32_t keyDataLength, const uint8_t* plainData, const uint32_t plainDataLength, uint8_t* signatureData, uint32_t* signatureDataLength, teeRsaSigAlg_t algorithm); /** * TEE_RSAVerify * * Verifies given data with RSA public key and return status * * @param keyData [in] Pointer to key data buffer * @param keyDataLength [in] Key data buffer length * @param plainData [in] Pointer to plain data to be signed * @param plainDataLength [in] Plain data length * @param signatureData [in] Pointer to signed data * @param signatureData [in] Plain data length * @param algorithm [in] RSA signature algorithm * @param validity [out] Signature validity */ teeResult_t TEE_RSAVerify( const uint8_t* keyData, const uint32_t keyDataLength, const uint8_t* plainData, const uint32_t plainDataLength, const uint8_t* signatureData, const uint32_t signatureDataLength, teeRsaSigAlg_t algorithm, bool *validity); /** * TEE_HMACKeyGenerate * * Generates random key for HMAC calculation and returns key data as wrapped object * (key is encrypted) * * @param keyData [out] Pointer to key data * @param keyDataLength [in] Key data buffer length * @param soLen [out] Key data secure object length */ teeResult_t TEE_HMACKeyGenerate( uint8_t* keyData, uint32_t keyDataLength, uint32_t* soLen); /** * TEE_HMACSign * * Signs given plain data and returns HMAC signature data * * @param keyData [in] Pointer to key data buffer * @param keyDataLength [in] Key data buffer length * @param plainData [in] Pointer to plain data to be signed * @param plainDataLength [in] Plain data length * @param signatureData [out] Pointer to signature data * @param signatureDataLength [out] Signature data length * @param digest [in] Digest type */ teeResult_t TEE_HMACSign( const uint8_t* keyData, const uint32_t keyDataLength, const uint8_t* plainData, const uint32_t plainDataLength, uint8_t* signatureData, uint32_t* signatureDataLength, teeDigest_t digest); /** * TEE_HMACVerify * * Verifies given data HMAC key data and return status * * @param keyData [in] Pointer to key data buffer * @param keyDataLength [in] Key data buffer length * @param plainData [in] Pointer to plain data to be signed * @param plainDataLength [in] Plain data length * @param signatureData [in] Pointer to signed data * @param signatureData [in] Plain data length * @param digest [in] Digest type * @param validity [out] Signature validity */ teeResult_t TEE_HMACVerify( const uint8_t* keyData, const uint32_t keyDataLength, const uint8_t* plainData, const uint32_t plainDataLength, const uint8_t* signatureData, const uint32_t signatureDataLength, teeDigest_t digest, bool *validity); /** * TEE_KeyImport * * Imports key data and returns key data as secure object * * Key data needs to be in the following format * * RSA key data: * |--key metadata--|--public modulus--|--public exponent--|--private exponent--| * * RSA CRT key data: * |--key metadata--|--public modulus--|--public exponent--|--P--|--Q--|--DP--|--DQ--|--Qinv--| * * Where: * P: secret prime factor * Q: secret prime factor * DP: d mod (p-1) * DQ: d mod (q-1) * Qinv: q^-1 mod p * * @param keyData [in] Pointer to key data * @param keyDataLength [in] Key data length * @param soData [out] Pointer to wrapped key data * @param soDataLength [out] Wrapped key data length */ teeResult_t TEE_KeyImport( const uint8_t* keyData, const uint32_t keyDataLength, uint8_t* soData, uint32_t* soDataLength); /** * TEE_GetPubKey * * Retrieves public key daya (modulus and exponent) from wrapped key data * * @param keyData [in] Pointer to key data * @param keyDataLength [in] Key data length * @param modulus [out] Pointer to public key modulus data * @param modulusLength [out] Modulus data length * @param exponent [out] Pointer to public key exponent data * @param exponentLength [out] Exponent data length */ teeResult_t TEE_GetPubKey( const uint8_t* keyData, const uint32_t keyDataLength, uint8_t* modulus, uint32_t* modulusLength, uint8_t* exponent, uint32_t* exponentLength); #ifdef __cplusplus } #endif #endif // __TLCTEEKEYMASTERIF_H__