libkeymaster/tlcTeeKeymaster_if.h

   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__