/*
 * Copyright (C) 2019 SAMSUNG S.LSI
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __GRDM_BL__H
#define __GRDM_BL__H

/**
 * @file grdm_bl.h
 * @brief GuardianM eSE bootloader APIs.
 */

/**
 * @ingroup grdm
 * @defgroup grdm_bl GRDM_BL
 * @brief GuardianM eSE bootloader APIs.
 *
 * This API provides bootloader functions.
 * @{
 */

#include <grdm_common.h>

/**
 * @brief Initialization to put key
 *
 * - API to prepare binding operation between BL and Guardian M.
 * - Guardian M shall return chip identifier.
 * - Limitations
 *  -# Chip ID buffer : Must be allocated at least 12 bytes
 *  -# Host ID buffer : Must be allocated at least 16 bytes
 *
 * @param[out] chipid     : Guardian M chip ID
 * @param[out] chipid_len : Length of \p chipid
 * @param[out] hostid     : ID of host that binds with chip
 * @param[out] hostid_len : Length of \p hostid
 * @param[out] BL_keyflag : BL key flag
 * @return Returns ::GRDM_NO_ERROR if succeeded and other value if failed.
 */
GRDM_RESULT grdm_BL_putkey_init (uint8_t* chipid, uint32_t* chipid_len,
		uint8_t* hostid, uint32_t* hostid_len, uint8_t* BL_keyflag);
/**
 * @brief Put key
 *
 * - API to put key and host identifier to Guardian M.
 *   Host identifier can be device identifier, such as device serial number,
 *   unique information of bound host.
 * - This process shall be performed only one thime.
 * - It is strongly recommended that this API should be called and success fully
 *   performed during factory process.
 * - Once key and host ID are injected, it is never overwritten and discarded.
 * - Limitations
 *  -# Key     : Must be 32 bytes
 *  -# Host ID : Must be 16 bytes
 *
 * @param[in] key        : Bootloader authkey
 * @param[in] key_len    : Length of \p key
 * @param[in] hostid     : ID of host that binds with chip
 * @param[in] hostid_len : Length of \p hostid
 * @return Returns ::GRDM_NO_ERROR if succeeded and other value if failed.
 */
GRDM_RESULT grdm_BL_putkey (uint8_t* key, uint8_t key_len,
		uint8_t* hostid, uint8_t hostid_len);
/**
 * @brief Store credential
 *
 * - API for bootloader to store BL credential.
 * - This operation shall be performed via secure channel.
 * - Input key is only used to open secure channel with Guardian M.
 *   Based on the key, Guardian M secure channel APIs shall derive
 *   secure channel session key(SCSK) set for channel protection.
 * - Limitations
 *  -# Key        : Must be 32 bytes
 *  -# Credential : Must be 256 bytes
 *
 * @param[in] key                : Bootloader authkey
 * @param[in] key_len            : Length of \p key
 * @param[in] BLcredential_index : Index of bootloader credential
 * @param[in] data               : Bootloader credential to write
 * @param[in] data_len           : Length of \p data
 * @return Returns ::GRDM_NO_ERROR if succeeded and other value if failed.
 */
GRDM_RESULT grdm_BL_storeCredential (uint8_t* key, uint8_t key_len,
		uint8_t BLcredential_index, uint8_t* data, uint32_t data_len);
/**
 * @brief Get credential
 *
 * - API for BL to get BL credential.
 * - This operation shall be performed via secure channel.
 * - Input key is only used to open secure channel with Guardian M.
 *   Based on the key, Guardian M secure channel APIs shall derive
 *   secure channel session key(SCSK) set for channel protection.
 * - Limitations
 *  -# Key               : Must be 32 bytes
 *  -# Credential buffer : Must be allocated at least 256 bytes
 *
 * @param[in]  key                : Bootloader authkey
 * @param[in]  key_len            : Length of \p key
 * @param[in]  BLcredential_index : Index of bootloader credential
 * @param[out] data               : Received bootloader credential
 * @param[out] data_len           : Length of \p data
 * @return Returns ::GRDM_NO_ERROR if succeeded and other value if failed.
 */
GRDM_RESULT grdm_BL_getCredential (uint8_t* key, uint8_t key_len,
		uint8_t BLcredential_index, uint8_t* data, uint32_t* data_len);

/**
 * @}
 */
#endif