pal_drbg.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_DRBG_H
00020 #define _PAL_DRBG_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 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 #include "pal.h" //added for PAL_INITIAL_RANDOM_SIZE value
00033 
00034 /*! \file pal_drbg.h
00035  *  \brief PAL DRBG.
00036  *   This file contains the real-time OS APIs and is a part of the PAL service API.
00037  *
00038  *   It provides thread, timers, semaphores, mutexes and memory pool management APIs
00039  *   as well as random API.
00040  */
00041 
00042 
00043 /*! \brief Generate random number into given buffer with given size in bytes.
00044  *
00045  * @param[out] randomBuf A buffer to hold the generated number.
00046  * @param[in] bufSizeBytes The size of the buffer and the size of the required random number to generate.
00047  *
00048  * \note `pal_init()` MUST be called before this function.
00049  * \note If non-volatile entropy is expected, the entropy must have been injected before this function is called. If entropy has not been injected to non-volatile memory, us `pal_plat_osEntropyInject()`.
00050  * \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.
00051  */
00052 palStatus_t pal_osRandomBuffer(uint8_t *randomBuf, size_t bufSizeBytes);
00053 
00054 /*! \brief Generate a 32-bit random number.
00055  *
00056  * @param[out] randomInt A 32-bit buffer to hold the generated number.
00057  *
00058  \note `pal_init()` MUST be called before this function.
00059  \note If non-volatile entropy is expected, the entropy must be in storage when this function is called. Non-volatile entropy may be injected using `pal_plat_osEntropyInject()`.
00060  \return PAL_SUCCESS on success, a negative value indicating a specific error code in case of failure.
00061  */
00062 palStatus_t pal_osRandom32bit(uint32_t *randomInt);
00063 
00064 
00065 #ifdef __cplusplus
00066 }
00067 #endif
00068 #endif //_PAL_DRBG_H