0ef1717155
Some checks failed
Basic Checks / license-check (push) Has been cancelled
Basic Checks / include-check (push) Has been cancelled
Basic Checks / style-check (push) Has been cancelled
Basic Checks / docs-check (push) Has been cancelled
Basic Checks / python-tests (push) Has been cancelled
Basic Checks / pin-validation (push) Has been cancelled
Basic Checks / cmake-checks (push) Has been cancelled
Basic Checks / frozen-tools-check (push) Has been cancelled
Publish or Update docker image for head of branch / prepare-tags (push) Has been cancelled
Release or update docker image for a released mbed-os version / prepare-tags (push) Has been cancelled
Publish or Update docker image for head of branch / build-container (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/amd64) (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/arm64) (push) Has been cancelled
Publish or Update docker image for head of branch / deploy-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / build-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/amd64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/arm64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / deploy-container (push) Has been cancelled
Prune temporary docker images / prune-images (push) Has been cancelled
121 lines
4.0 KiB
C
121 lines
4.0 KiB
C
/***************************************************************************//**
|
|
* \file cyhal_trng.h
|
|
*
|
|
* \brief
|
|
* Provides a high level interface for interacting with the Cypress True Random
|
|
* Number Generator. This interface abstracts out the chip specific details. If
|
|
* any chip specific functionality is necessary, or performance is critical the
|
|
* low level functions can be used directly.
|
|
*
|
|
********************************************************************************
|
|
* \copyright
|
|
* Copyright 2018-2021 Cypress Semiconductor Corporation
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*******************************************************************************/
|
|
|
|
/**
|
|
* \addtogroup group_hal_trng TRNG (True Random Number Generator)
|
|
* \ingroup group_hal
|
|
* \{
|
|
* High level interface to the True Random Number Generator (TRNG).
|
|
*
|
|
* This block uses dedicated hardware to efficiently generate true random numbers.
|
|
*
|
|
* \section subsection_trng_features Features
|
|
* * Number generated is statistically random
|
|
* * Based on physical processes exhibiting random variation
|
|
* * Generated sequences of numbers cannot be duplicated by running the process again
|
|
* * Uses polynomial generators with fixed and programmable polynomials
|
|
*
|
|
* \note This driver is not intended to be used as a security library. If a full security library
|
|
* is needed something like Mbed TLS should be used instead.
|
|
*
|
|
* \section subsection_trng_quickstart Quick Start
|
|
*
|
|
* \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.
|
|
*
|
|
* See \ref subsection_trng_use_case_1.
|
|
*
|
|
* \subsection subsection_trng_use_case_1 Simple TRNG number generation example
|
|
* The following snippet initializes a TRNG and generates a true random number.
|
|
*
|
|
* \snippet hal_trng.c snippet_cyhal_trng_simple_init
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include "cy_result.h"
|
|
#include "cyhal_hw_types.h"
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \addtogroup group_hal_results_trng TRNG HAL Results
|
|
* TRNG specific return codes
|
|
* \ingroup group_hal_results
|
|
* \{ *//**
|
|
*/
|
|
|
|
/** An invalid argument was passed to a function. */
|
|
#define CYHAL_TRNG_RSLT_ERR_BAD_ARGUMENT \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_TRNG, 0))
|
|
/** Hardware error in the crypto block. This will only occur if the Ring oscillators in the TRNG generator are explicitly
|
|
* disabled during TRNG generation.
|
|
*/
|
|
#define CYHAL_TRNG_RSLT_ERR_HW \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_TRNG, 1))
|
|
|
|
/**
|
|
* \}
|
|
*/
|
|
|
|
/** Initialize the random number generator.
|
|
*
|
|
* @param[out] obj Pointer to a random number generator object. The caller must
|
|
* allocate the memory for this object but the init function will initialize its contents.
|
|
* @return The status of the init request
|
|
*
|
|
* Returns \ref CY_RSLT_SUCCESS if the operation was successful
|
|
*/
|
|
cy_rslt_t cyhal_trng_init(cyhal_trng_t *obj);
|
|
|
|
/** Release the random number generator.
|
|
*
|
|
* @param[in,out] obj The random number generator object
|
|
*/
|
|
void cyhal_trng_free(cyhal_trng_t *obj);
|
|
|
|
/** Generate a random number.
|
|
*
|
|
* @param[in] obj The random number generator object
|
|
* @return The random number generated
|
|
*
|
|
* See \ref subsection_trng_use_case_1
|
|
*/
|
|
uint32_t cyhal_trng_generate(const cyhal_trng_t *obj);
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#ifdef CYHAL_TRNG_IMPL_HEADER
|
|
#include CYHAL_TRNG_IMPL_HEADER
|
|
#endif /* CYHAL_TRNG_IMPL_HEADER */
|
|
|
|
/** \} group_hal_trng */
|