pal_entropy.h

00001 /*******************************************************************************
00002 * Copyright 2019 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_ENTROPY_H
00019 #define _PAL_ENTROPY_H
00020 
00021 #ifndef _PAL_H
00022 #error "Please do not include this file directly, use pal.h instead"
00023 #endif
00024 
00025 #ifdef __cplusplus
00026 extern "C" {
00027 #endif
00028 
00029 /** \file pal_entropy.h
00030  *  \brief PAL entropy.
00031  *   This file contains entropy injection and is part of the PAL API.
00032  */
00033 
00034 /** \brief Inject entropy to non-volatile memory, so that the random number generator may use it.
00035  *
00036  * In addition to OS functions, the module implementing `pal_drbg.h` will hold a deterministic
00037  * random bit generator (DRBG) instance that works with the entropy injected by this function.
00038  *
00039  * \note This API call must be placed before any function that may attempt to generate a
00040  * random number, both by the OS or PAL DRBG. After this API call,
00041  * `pal_osRandomBuffer()`` calls from `pal_drbg.h` will succeed.
00042  *
00043  * @param entropyBuf - pointer to buffer containing the entropy.
00044  * @param bufSizeBytes - size of `entropyBuf` in bytes.
00045  *
00046  * @return PAL_SUCCESS - if operation is successful
00047  * @return PAL_ERR_NOT_SUPPORTED - code compiled in a way that does not expect entropy to be injected. TRNG must be available to inject entropy.
00048  * @return PAL_ERR_INVALID_ARGUMENT - `bufSizeBytes` too small.
00049  * @return PAL_ERR_ENTROPY_EXISTS - Entropy already injected.
00050  * @return PAL_ERR_GENERIC_FAILURE - Another cause of error.
00051  */
00052 palStatus_t pal_osEntropyInject(const uint8_t *entropyBuf, size_t bufSizeBytes);
00053 
00054 #ifdef __cplusplus
00055 }
00056 #endif
00057 #endif // _PAL_ENTROPY_H