xref: /hardware/samsung_slsi/exynos5/libkeymaster/tlcTeeKeymaster_if.h

/**
 * @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 <stdint.h>
#include <stdbool.h>


/**
 * 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__