pal_plat_drbg.h

00001 /*******************************************************************************
00002  * Copyright 2016, 2017 ARM Ltd.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  *******************************************************************************/
00016 
00017 
00018 #ifndef _PAL_PLAT_DRBG_H
00019 #define _PAL_PLAT_DRBG_H
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 #include "pal.h"
00026 
00027 
00028 /*! \file pal_plat_drbg.h
00029  *  \brief PAL DRBG - platform.
00030  *   This file contains the real-time OS APIs that need to be implemented in the platform layer.
00031  */
00032 
00033 
00034 
00035 /*! \brief Initialize all data structures (semaphores, mutexes, memory pools, message queues) at system initialization.
00036  *
00037  *   In case of a failure in any of the initializations, the function returns an error and stops the rest of the initializations.
00038  * \return PAL_SUCCESS(0) in case of success, PAL_ERR_CREATION_FAILED in case of failure.
00039  */
00040 palStatus_t pal_plat_DRBGInit(void);
00041 
00042 /*! \brief De-initialize thread objects.
00043  */
00044 palStatus_t pal_plat_DRBGDestroy(void);
00045 
00046 // XXX: following two are really easy to mix up, a better naming needs to be done
00047 //
00048 // * pal_plat_osRandomBuffer_public() - The one which is called by pal_osRandomBuffer(), one which
00049 //                                      will block until there is enough entropy harvested
00050 //
00051 // * pal_plat_osRandomBuffer() - The lower level part, used by pal_plat_osRandomBuffer_public(),
00052 //                                  this is nonblocking version which will return as much as possible.
00053 //                               Perhaps this should be pal_plat_GetosRandomBufferFromHW() to align
00054 //                               with logic used with similar purpose function as pal_plat_osGetRoTFromHW().
00055 
00056 /*! \brief Generate a random number into the given buffer with the given size in bytes.
00057  *
00058  * @param[out] randomBuf A buffer to hold the generated number.
00059  * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate.
00060  * @param[out] actualRandomSizeBytes The actual size of the written random data to the output buffer.
00061  \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00062  \note In case the platform was able to provide random data with non-zero size and less than `bufSizeBytes`the function must return `PAL_ERR_RTOS_TRNG_PARTIAL_DATA`
00063  */
00064 palStatus_t pal_plat_osRandomBuffer(uint8_t *randomBuf, size_t bufSizeBytes, size_t* actualRandomSizeBytes);
00065 
00066 /*! \brief Generate random number into given buffer with given size in bytes.
00067  *
00068  * @param[out] randomBuf A buffer to hold the generated number.
00069  * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate.
00070  *
00071  * \note `pal_init()` MUST be called before this function
00072  * \note If non-volatile entropy is expected, the entropy must have been injected before this function is called. Non-volatile entropy may be injected using `pal_plat_osEntropyInject()`.
00073  * \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.
00074  */
00075 palStatus_t pal_plat_osRandomBuffer_blocking(uint8_t *randomBuf, size_t bufSizeBytes);
00076 
00077 #ifdef __cplusplus
00078 }
00079 #endif
00080 #endif //_PAL_PLAT_RTOS_H