/*
 * Copyright (C) 2017 Samsung Electronics Co., Ltd. All rights reserved.
 *
 * Mobile Communications Business,
 * IT & Mobile Communications, Samsung Electronics Co., Ltd.
 *
 * This software and its documentation are confidential and proprietary
 * information of Samsung Electronics Co., Ltd. No part of the software and
 * documents may be copied, reproduced, transmitted, translated, or reduced to
 * any electronic medium or machine-readable form without the prior written
 * consent of Samsung Electronics.
 *
 * Samsung Electronics makes no representations with respect to the contents,
 * and assumes no responsibility for any errors that might appear in the
 * software and documents. This publication and the contents hereof are subject
 * to change without notice.
 */
 
#ifndef __IFAA_KM_H__
#define __IFAA_KM_H__

#include <stdint.h>

#ifndef IN 
#define IN
#endif

#ifndef OUT
#define OUT
#endif

#ifndef IN_OUT
#define IN_OUT
#endif

typedef uint32_t ifaa_km_result_t;

#define IFAA_KM_SUCCESS                       0x00000000    /* Operation success */

/**
 * @brief 
 *    API for provisioning the attestation key for IFAA.
 *    
 *    This attestation key must be injected by SKPM(Samsung Key Provisioning Manger) and delivered
 *    to IFAA TA as encrypted. First, This API unwraps encrypted skpm_key_handle and then parse 
 *    unwrapped key handle to identify the key and other contents. Finally, it provision them on RPMB. 
 *    The unwrapping protocol and parsing rule is totally based on the contract which is shared 
 *    between SKPM TA and IFAA TA. That's why the key should be given from SKPM TA. The attestation 
 *    key is written on RPMB and never returned as the result of the API.
 *    
 *    Currently, RSA 2048 key length is supported.
 *
 * @param[in] skpm_key_handle 
 * @param[in] skpm_key_handle_len 
 *
 * @requires 
 *   skpm_key_handle is a wrapped key handle provided by SKPM TA. It's retrieved through key_blob
 *      parameter on ISkpmService#SkpmServiceCreateGetKeySession. Please note that it should be 
 *      decoded first before passing it to ifaa_km_provision_key API according to encoding_type on 
 *      ISkpmService#SkpmServiceCreateGetKeySession.(key_blob -> String -> decode -> skpm_key_handle)
 *      so, ISkpmService#SkpmServiceCreateGetKeySession is follwed by ifaa_km_provision_key. Specially
 *      with QSEE, while invoking these two APIs, both SKPM TA and IFAA TA should be kept as loaded.
 *   skpm_key_handle_len should indicate the exact size of skpm_key_handle.
 *
 * @return IFAA_KM_SUCCESS indicates success, all other values indicate failure and
 *     correspond to a specific error code. 
 */
ifaa_km_result_t 
ifaa_km_provision_key(
    IN const uint8_t* skpm_key_handle, 
    IN const uint32_t skpm_key_handle_len
);

/**
 * @brief 
 *    API for signing given data using the attestation key for IFAA.
 *    
 *    This API read the attestation key from RPMB and sign to_be_signed_data by using it. Finally,
 *    the raw signature will be returned through signature output parameter. Because the attestation
 *    key is not exposed to the caller, only the key, which has been provisioned by 
 *    ifaa_km_provision_key, will be used.
 *
 *    Currently, RSASSA-PKCS1-v1_5 scheme with RSA 2048 key length is supported.
 *
 * @param[in]       to_be_signed_data 
 * @param[in]       to_be_signed_data_len 
 * @param[out]      signature 
 * @param[in, out]  signature_len 
 *
 * @requires 
 *   to_be_signed_data is to be signed data.
 *   to_be_signed_data_len should indicate the exact size of to_be_signed_data.
 *   signature includes the result of this sign operation for to_be_signed_data. This output buffer 
 *      size must be more than or equal to 256 bytes.
 *   signature_len should indicate the exact size of signature output parameter, and this must be
 *      greater than or equal to 256 to allow room for the signature using RSA 2048 key length.
 *      signature_len is modified to reflect the exact length of the data 
 *      written into signature. If success using RSA 2048 key length, it will be set as 256.
 *
 * @return IFAA_KM_SUCCESS indicates success, all other values indicate failure and
 *     correspond to a specific error code. 
 */
ifaa_km_result_t 
ifaa_km_sign(
    IN const uint8_t* to_be_signed_data,
    IN const uint32_t to_be_signed_data_len, 
    OUT uint8_t* signature, 
    IN_OUT uint32_t* signature_len
);

#endif //end of __IFAA_KM_H__