pal_rot.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef _PAL_ROT_H
00020 #define _PAL_ROT_H
00021 
00022 #ifndef _PAL_H
00023     #error "Please do not include this file directly, use pal.h instead"
00024 #endif
00025 
00026 #include <stdint.h>
00027 
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 
00033 
00034 /*! \file pal_rot.h
00035 *  \brief PAL ROT.
00036 *   This file contains the ROT (root of trust) API.
00037 */
00038 
00039 
00040 //! Device key types supported in PAL.
00041 typedef enum  palDeviceKeyType {
00042     palOsStorageEncryptionKey128Bit = 0, /*! 128bit storage encryption key derived from RoT. */
00043     palOsStorageSignatureKey128Bit  = 1, /*! 128bit storage signature key derived from RoT. */
00044     palOsStorageHmacSha256  = 2
00045 } palDevKeyType_t;
00046 
00047 
00048 /*! Return a device unique key derived from the root of trust.
00049 *
00050 * @param[in] keyType The type of key to derive.
00051 * @param[in,out] key A 128-bit OR 256-bit buffer to hold the derived key, size is defined according to the `keyType`.
00052 * @param[in] keyLenBytes The size of buffer to hold the 128-bit OR 256-bit key.
00053 * \return PAL_SUCCESS in case of success and one of the following error codes in case of failure: \n
00054 * PAL_ERR_GET_DEV_KEY - an error in key derivation.\n
00055 * PAL_ERR_INVALID_ARGUMENT - invalid parameter.
00056 */
00057 palStatus_t pal_osGetDeviceKey(palDevKeyType_t keyType, uint8_t *key, size_t keyLenBytes);
00058 
00059 
00060 /*! Sets a root of trust key. The size of the key must be 16 bytes.
00061 * This function is not implemented for HW RoT configuration.
00062 *
00063 * @param[in] key A 16 bytes buffer with a root of trust key to set.
00064 * @param[in] keyLenBytes The size of the buffer must be 16 bytes.
00065 * \return PAL_SUCCESS in case of success and one of the following error codes in case of failure: \n
00066 * PAL_ERR_ITEM_EXIST - RoT key already exists.\n
00067 * PAL_ERR_INVALID_ARGUMENT - invalid parameter.\n
00068 * PAL_ERR_GENERIC_FAILURE - set operation failed.\n
00069 * PAL_ERR_NOT_IMPLEMENTED - the function is not implemented for current configuration.\n
00070 */
00071 palStatus_t pal_osSetRoT(uint8_t *key, size_t keyLenBytes);
00072 #ifdef __cplusplus
00073 }
00074 #endif
00075 #endif //_PAL_ROT_H