1 /** 2 * @file tlcTeeKeymaster_if.h 3 * @brief Contains TEE Keymaster trustlet connector interface definitions 4 * 5 * Copyright Giesecke & Devrient GmbH 2012 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 3. The name of the author may not be used to endorse or promote 16 * products derived from this software without specific prior 17 * written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 20 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 25 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef __TLCTEEKEYMASTERIF_H__ 33 #define __TLCTEEKEYMASTERIF_H__ 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 #include <stdint.h> 40 #include <stdbool.h> 41 42 43 /** 44 * Key sizes 45 */ 46 #define TEE_RSA_KEY_SIZE_512 512 47 #define TEE_RSA_KEY_SIZE_1024 1024 48 #define TEE_RSA_KEY_SIZE_2048 2048 49 50 51 /* error codes */ 52 typedef enum 53 { 54 TEE_ERR_NONE = 0, 55 TEE_ERR_FAIL = 1, 56 TEE_ERR_INVALID_BUFFER = 2, 57 TEE_ERR_BUFFER_TOO_SMALL = 3, 58 TEE_ERR_NOT_IMPLEMENTED = 4, 59 TEE_ERR_SESSION = 5, 60 TEE_ERR_MC_DEVICE = 6, 61 TEE_ERR_NOTIFICATION = 7, 62 TEE_ERR_MEMORY = 8, 63 TEE_ERR_MAP = 9 64 /* more can be added as required */ 65 } teeResult_t; 66 67 68 /* RSA key pair types */ 69 typedef enum { 70 TEE_KEYPAIR_RSA = 1, /**< RSA public and RSA private key. */ 71 TEE_KEYPAIR_RSACRT = 2 /**< RSA public and RSA CRT private key. */ 72 } teeRsaKeyPairType_t; 73 74 75 /* Supported RSA signature algorithms */ 76 typedef enum 77 { 78 /* RSA */ 79 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. */ 80 TEE_RSA_SHA_ISO9796_MR = 2, /**< 20-byte SHA-1 digest, padded according to the ISO9796-2 specification and encrypted using RSA. */ 81 TEE_RSA_SHA_PKCS1 = 3, /**< 20-byte SHA-1 digest, padded according to the PKCS#1 (v1.5) scheme, and encrypted using RSA. */ 82 TEE_RSA_SHA256_PSS = 4, /**< SHA-256 digest and PSS padding */ 83 TEE_RSA_SHA1_PSS = 5, /**< SHA-256 digest and PSS padding */ 84 TEE_RSA_NODIGEST_NOPADDING = 6, /**< No digest and padding */ 85 } teeRsaSigAlg_t; 86 87 88 /* Digest types */ 89 typedef enum 90 { 91 TEE_DIGEST_SHA1, 92 TEE_DIGEST_SHA256 93 } teeDigest_t; 94 95 96 /** 97 * RSA private key metadata (Private modulus and exponent lengths) 98 */ 99 typedef struct { 100 uint32_t lenprimod; /**< Private key modulus length */ 101 uint32_t lenpriexp; /**< Private key exponent length */ 102 } teeRsaPrivKeyMeta_t; 103 104 105 /** 106 * RSA CRT private key metadata (Private modulus and exponent lengths) 107 */ 108 typedef struct { 109 uint32_t lenprimod; /**< Private key modulus length */ 110 uint32_t lenp; /**< Prime p length */ 111 uint32_t lenq; /**< Prime q length */ 112 uint32_t lendp; /**< DP length */ 113 uint32_t lendq; /**< DQ length */ 114 uint32_t lenqinv; /**< QP length */ 115 } teeRsaCrtPrivKeyMeta_t; 116 117 118 /** 119 * Key metadata (public key hash, key size, modulus/exponent lengths, etc..) 120 */ 121 typedef struct { 122 uint32_t keytype; /**< Key type, e.g. RSA */ 123 uint32_t keysize; /**< Key size, e.g. 1024, 2048 */ 124 uint32_t lenpubmod; /**< Public key modulus length */ 125 uint32_t lenpubexp; /**< Public key exponent length */ 126 union { 127 teeRsaPrivKeyMeta_t rsapriv; /**< RSA private key */ 128 teeRsaCrtPrivKeyMeta_t rsacrtpriv; /**< RSA CRT private key */ 129 }; 130 uint32_t rfu; /**< Reserved for future use */ 131 uint32_t rfulen; /**< Reserved for future use */ 132 } teeRsaKeyMeta_t; 133 134 /** 135 * TEE_RSAGenerateKeyPair 136 * 137 * Generates RSA key pair and returns key pair data as wrapped object 138 * 139 * @param keyType [in] Key pair type. RSA or RSACRT 140 * @param keyData [in] Pointer to the key data buffer 141 * @param keyDataLength [in] Key data buffer length 142 * @param keySize [in] Key size 143 * @param exponent [in] Exponent number 144 * @param soLen [out] Key data secure object length 145 */ 146 teeResult_t TEE_RSAGenerateKeyPair( 147 teeRsaKeyPairType_t keyType, 148 uint8_t* keyData, 149 uint32_t keyDataLength, 150 uint32_t keySize, 151 uint32_t exponent, 152 uint32_t* soLen); 153 154 155 /** 156 * TEE_RSASign 157 * 158 * Signs given plain data and returns signature data 159 * 160 * @param keyData [in] Pointer to key data buffer 161 * @param keyDataLength [in] Key data buffer length 162 * @param plainData [in] Pointer to plain data to be signed 163 * @param plainDataLength [in] Plain data length 164 * @param signatureData [out] Pointer to signature data 165 * @param signatureDataLength [out] Signature data length 166 * @param algorithm [in] RSA signature algorithm 167 */ 168 teeResult_t TEE_RSASign( 169 const uint8_t* keyData, 170 const uint32_t keyDataLength, 171 const uint8_t* plainData, 172 const uint32_t plainDataLength, 173 uint8_t* signatureData, 174 uint32_t* signatureDataLength, 175 teeRsaSigAlg_t algorithm); 176 177 178 /** 179 * TEE_RSAVerify 180 * 181 * Verifies given data with RSA public key and return status 182 * 183 * @param keyData [in] Pointer to key data buffer 184 * @param keyDataLength [in] Key data buffer length 185 * @param plainData [in] Pointer to plain data to be signed 186 * @param plainDataLength [in] Plain data length 187 * @param signatureData [in] Pointer to signed data 188 * @param signatureData [in] Plain data length 189 * @param algorithm [in] RSA signature algorithm 190 * @param validity [out] Signature validity 191 */ 192 teeResult_t TEE_RSAVerify( 193 const uint8_t* keyData, 194 const uint32_t keyDataLength, 195 const uint8_t* plainData, 196 const uint32_t plainDataLength, 197 const uint8_t* signatureData, 198 const uint32_t signatureDataLength, 199 teeRsaSigAlg_t algorithm, 200 bool *validity); 201 202 203 /** 204 * TEE_HMACKeyGenerate 205 * 206 * Generates random key for HMAC calculation and returns key data as wrapped object 207 * (key is encrypted) 208 * 209 * @param keyData [out] Pointer to key data 210 * @param keyDataLength [in] Key data buffer length 211 * @param soLen [out] Key data secure object length 212 */ 213 teeResult_t TEE_HMACKeyGenerate( 214 uint8_t* keyData, 215 uint32_t keyDataLength, 216 uint32_t* soLen); 217 218 219 /** 220 * TEE_HMACSign 221 * 222 * Signs given plain data and returns HMAC signature data 223 * 224 * @param keyData [in] Pointer to key data buffer 225 * @param keyDataLength [in] Key data buffer length 226 * @param plainData [in] Pointer to plain data to be signed 227 * @param plainDataLength [in] Plain data length 228 * @param signatureData [out] Pointer to signature data 229 * @param signatureDataLength [out] Signature data length 230 * @param digest [in] Digest type 231 */ 232 teeResult_t TEE_HMACSign( 233 const uint8_t* keyData, 234 const uint32_t keyDataLength, 235 const uint8_t* plainData, 236 const uint32_t plainDataLength, 237 uint8_t* signatureData, 238 uint32_t* signatureDataLength, 239 teeDigest_t digest); 240 241 242 /** 243 * TEE_HMACVerify 244 * 245 * Verifies given data HMAC key data and return status 246 * 247 * @param keyData [in] Pointer to key data buffer 248 * @param keyDataLength [in] Key data buffer length 249 * @param plainData [in] Pointer to plain data to be signed 250 * @param plainDataLength [in] Plain data length 251 * @param signatureData [in] Pointer to signed data 252 * @param signatureData [in] Plain data length 253 * @param digest [in] Digest type 254 * @param validity [out] Signature validity 255 */ 256 teeResult_t TEE_HMACVerify( 257 const uint8_t* keyData, 258 const uint32_t keyDataLength, 259 const uint8_t* plainData, 260 const uint32_t plainDataLength, 261 const uint8_t* signatureData, 262 const uint32_t signatureDataLength, 263 teeDigest_t digest, 264 bool *validity); 265 266 267 /** 268 * TEE_KeyImport 269 * 270 * Imports key data and returns key data as secure object 271 * 272 * Key data needs to be in the following format 273 * 274 * RSA key data: 275 * |--key metadata--|--public modulus--|--public exponent--|--private exponent--| 276 * 277 * RSA CRT key data: 278 * |--key metadata--|--public modulus--|--public exponent--|--P--|--Q--|--DP--|--DQ--|--Qinv--| 279 * 280 * Where: 281 * P: secret prime factor 282 * Q: secret prime factor 283 * DP: d mod (p-1) 284 * DQ: d mod (q-1) 285 * Qinv: q^-1 mod p 286 * 287 * @param keyData [in] Pointer to key data 288 * @param keyDataLength [in] Key data length 289 * @param soData [out] Pointer to wrapped key data 290 * @param soDataLength [out] Wrapped key data length 291 */ 292 teeResult_t TEE_KeyImport( 293 const uint8_t* keyData, 294 const uint32_t keyDataLength, 295 uint8_t* soData, 296 uint32_t* soDataLength); 297 298 299 /** 300 * TEE_GetPubKey 301 * 302 * Retrieves public key daya (modulus and exponent) from wrapped key data 303 * 304 * @param keyData [in] Pointer to key data 305 * @param keyDataLength [in] Key data length 306 * @param modulus [out] Pointer to public key modulus data 307 * @param modulusLength [out] Modulus data length 308 * @param exponent [out] Pointer to public key exponent data 309 * @param exponentLength [out] Exponent data length 310 */ 311 teeResult_t TEE_GetPubKey( 312 const uint8_t* keyData, 313 const uint32_t keyDataLength, 314 uint8_t* modulus, 315 uint32_t* modulusLength, 316 uint8_t* exponent, 317 uint32_t* exponentLength); 318 319 320 #ifdef __cplusplus 321 } 322 #endif 323 324 #endif // __TLCTEEKEYMASTERIF_H__ 325