pal_plat_entropy.h

00001 /*******************************************************************************
00002 * Copyright 2016-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_PLAT_ENTROPY_H
00019 #define _PAL_PLAT_ENTROPY_H
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 #include "pal.h"
00026 #include "pal_entropy.h"
00027 #include <stdint.h>
00028 
00029 /** \file pal_plat_entropy.h
00030  *  \brief PAL entropy - platform.
00031  *   This file contains entropy injection as part of the platform layer.
00032  */
00033 
00034 //! The maximum entropy size that may be injected to non-volatile memory
00035 #define PAL_PLAT_MAX_ENTROPY_SIZE 48
00036 
00037 /** \brief Inject entropy to non-volatile memory, so that the random number generator may use it.
00038  *
00039  * In addition to OS functions, the module implementing `pal_plat_drbg.h` will hold a deterministic
00040  * random bit generator (DRBG) instance that works with the entropy injected by this function.
00041  *
00042  * Note: This API call must be placed prior to any function that may attempt to generate a
00043  * random number, both by the OS or PAL platform DRBG. After this API call,
00044  * `pal_plat_osRandomBuffer_blocking()` calls from `pal_plat_drbg.h` will succeed.
00045  *
00046  * @param entropyBuf - pointer to buffer containing the entropy.
00047  * @param bufSizeBytes - size of `entropyBuf` in bytes.
00048  *
00049  * @return PAL_SUCCESS - if operation is successful.
00050  * @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.
00051  * @return PAL_ERR_INVALID_ARGUMENT - `bufSizeBytes` too small.
00052  * @return PAL_ERR_ENTROPY_EXISTS - Entropy already injected.
00053  * @return PAL_ERR_GENERIC_FAILURE - Another cause of error.
00054  */
00055 palStatus_t pal_plat_osEntropyInject(const uint8_t *entropyBuf, size_t bufSizeBytes);
00056 
00057 #ifdef __cplusplus
00058 }
00059 #endif
00060 #endif // _PAL_PLAT_ENTROPY_H