1 /***************************************************************************//** 2 * \file cyhal_trng.h 3 * 4 * \brief 5 * Provides a high level interface for interacting with the Infineon True Random 6 * Number Generator. This interface abstracts out the chip specific details. If 7 * any chip specific functionality is necessary, or performance is critical the 8 * low level functions can be used directly. 9 * 10 ******************************************************************************** 11 * \copyright 12 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 *******************************************************************************/ 29 30 /** 31 * \addtogroup group_hal_trng TRNG (True Random Number Generator) 32 * \ingroup group_hal 33 * \{ 34 * High level interface to the True Random Number Generator (TRNG). 35 * 36 * This block uses dedicated hardware to efficiently generate true random numbers. 37 * 38 * \section subsection_trng_features Features 39 * * Number generated is statistically random 40 * * Based on physical processes exhibiting random variation 41 * * Generated sequences of numbers cannot be duplicated by running the process again 42 * * Uses polynomial generators with fixed and programmable polynomials 43 * 44 * \note This driver is not intended to be used as a security library. If a full security library 45 * is needed something like Mbed TLS should be used instead. 46 * 47 * \section subsection_trng_quickstart Quick Start 48 * 49 * \ref cyhal_trng_init initializes the TRNG and passes a pointer to the **TRNG** block through the **obj** object of type \ref cyhal_trng_t. 50 * 51 * See \ref subsection_trng_use_case_1. 52 * 53 * \subsection subsection_trng_use_case_1 Simple TRNG number generation example 54 * The following snippet initializes a TRNG and generates a true random number. 55 * 56 * \snippet hal_trng.c snippet_cyhal_trng_simple_init 57 */ 58 59 #pragma once 60 61 #include <stdint.h> 62 #include <stdbool.h> 63 #include "cy_result.h" 64 #include "cyhal_hw_types.h" 65 66 #if defined(__cplusplus) 67 extern "C" { 68 #endif 69 70 /** \addtogroup group_hal_results_trng TRNG HAL Results 71 * TRNG specific return codes 72 * \ingroup group_hal_results 73 * \{ *//** 74 */ 75 76 /** An invalid argument was passed to a function. */ 77 #define CYHAL_TRNG_RSLT_ERR_BAD_ARGUMENT \ 78 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_TRNG, 0)) 79 /** Hardware error in the crypto block. This will only occur if the Ring oscillators in the TRNG generator are explicitly 80 * disabled during TRNG generation. 81 */ 82 #define CYHAL_TRNG_RSLT_ERR_HW \ 83 (CY_RSLT_CREATE_EX(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_HAL, CYHAL_RSLT_MODULE_TRNG, 1)) 84 85 /** 86 * \} 87 */ 88 89 /** Initialize the random number generator. 90 * 91 * @param[out] obj Pointer to a random number generator object. The caller must 92 * allocate the memory for this object but the init function will initialize its contents. 93 * @return The status of the init request 94 * 95 * Returns \ref CY_RSLT_SUCCESS if the operation was successful 96 */ 97 cy_rslt_t cyhal_trng_init(cyhal_trng_t *obj); 98 99 /** Release the random number generator. 100 * 101 * @param[in,out] obj The random number generator object 102 */ 103 void cyhal_trng_free(cyhal_trng_t *obj); 104 105 /** Generate a random number. 106 * 107 * @param[in] obj The random number generator object 108 * @return The random number generated 109 * 110 * See \ref subsection_trng_use_case_1 111 */ 112 uint32_t cyhal_trng_generate(const cyhal_trng_t *obj); 113 114 #if defined(__cplusplus) 115 } 116 #endif 117 118 #ifdef CYHAL_TRNG_IMPL_HEADER 119 #include CYHAL_TRNG_IMPL_HEADER 120 #endif /* CYHAL_TRNG_IMPL_HEADER */ 121 122 /** \} group_hal_trng */ 123
