mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_EFM32PG12_STK3402/TOOLCHAIN_ARM_STD/sl_trng.h@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 145:64910690c574 1 /**
AnnaBridge 145:64910690c574 2 * \file sl_trng.h
AnnaBridge 145:64910690c574 3 *
AnnaBridge 145:64910690c574 4 * \brief True Random Number Generator (TRNG) driver for Silicon Labs devices
AnnaBridge 145:64910690c574 5 *
AnnaBridge 145:64910690c574 6 * Copyright (C) 2016, Silicon Labs, http://www.silabs.com
AnnaBridge 145:64910690c574 7 * SPDX-License-Identifier: Apache-2.0
AnnaBridge 145:64910690c574 8 *
AnnaBridge 145:64910690c574 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
AnnaBridge 145:64910690c574 10 * not use this file except in compliance with the License.
AnnaBridge 145:64910690c574 11 * You may obtain a copy of the License at
AnnaBridge 145:64910690c574 12 *
AnnaBridge 145:64910690c574 13 * http://www.apache.org/licenses/LICENSE-2.0
AnnaBridge 145:64910690c574 14 *
AnnaBridge 145:64910690c574 15 * Unless required by applicable law or agreed to in writing, software
AnnaBridge 145:64910690c574 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
AnnaBridge 145:64910690c574 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
AnnaBridge 145:64910690c574 18 * See the License for the specific language governing permissions and
AnnaBridge 145:64910690c574 19 * limitations under the License.
AnnaBridge 145:64910690c574 20 */
AnnaBridge 145:64910690c574 21 #ifndef SL_TRNG_H
AnnaBridge 145:64910690c574 22 #define SL_TRNG_H
AnnaBridge 145:64910690c574 23
AnnaBridge 145:64910690c574 24 /***************************************************************************//**
AnnaBridge 145:64910690c574 25 * \addtogroup sl_crypto_trng Silicon Labs True Random Number Generator Plugin
AnnaBridge 145:64910690c574 26 * \brief True Random Number Generator (TRNG) driver for Silicon Labs devices.
AnnaBridge 145:64910690c574 27 *
AnnaBridge 145:64910690c574 28 * \details The EFR32xG12 and EFM32xG12 and newer Silicon Labs devices contains
AnnaBridge 145:64910690c574 29 * a True Random Number Generator (TRNG) peripheral. The TRNG is a
AnnaBridge 145:64910690c574 30 * non-deterministic random number generator based on a full hardware solution.
AnnaBridge 145:64910690c574 31 * The TRNG contains a 64 x 32-bit FIFO for reading out random numbers.
AnnaBridge 145:64910690c574 32 *
AnnaBridge 145:64910690c574 33 * The samples from entropy source within the TRNG are monitored permanently by
AnnaBridge 145:64910690c574 34 * 4 built in tests that detect issues with the noise source. The tests are
AnnaBridge 145:64910690c574 35 * specified in NIST-800-90B and AIS31. The tests that are always checking the
AnnaBridge 145:64910690c574 36 * entropy source are "Repetition Count Test", "Adaptive Proportion Test
AnnaBridge 145:64910690c574 37 * (64-sample window)", "Adaptive Proportion Test (4096-sample window)" and
AnnaBridge 145:64910690c574 38 * the "AIS31 Online Test".
AnnaBridge 145:64910690c574 39 *
AnnaBridge 145:64910690c574 40 * In addition the TRNG has options for running startup tests. When these tests
AnnaBridge 145:64910690c574 41 * are enabled the TRNG FIFO will not contains any data before all the startup
AnnaBridge 145:64910690c574 42 * tests have passed. There are 4 TRNG startup tests, 3 of the tests are
AnnaBridge 145:64910690c574 43 * specified in NIST-800-90B. These are the "Repetition Count Test", "Adaptive
AnnaBridge 145:64910690c574 44 * Proportion Test (64-sample window)" and "Adaptive Proportion Test
AnnaBridge 145:64910690c574 45 * (4096-sample window)". The last startup test is the AIS31 startup test. By
AnnaBridge 145:64910690c574 46 * default when using this driver all the startup tests are enabled.
AnnaBridge 145:64910690c574 47 *
AnnaBridge 145:64910690c574 48 * \{
AnnaBridge 145:64910690c574 49 ******************************************************************************/
AnnaBridge 145:64910690c574 50
AnnaBridge 145:64910690c574 51 #include "em_device.h"
AnnaBridge 145:64910690c574 52 #include <stddef.h>
AnnaBridge 145:64910690c574 53
AnnaBridge 145:64910690c574 54 /* TRNG specific error codes: */
AnnaBridge 145:64910690c574 55 #define SL_TRNG_ERR_BASE (0xF100E000)
AnnaBridge 145:64910690c574 56
AnnaBridge 145:64910690c574 57 /** Conditioning test failed. */
AnnaBridge 145:64910690c574 58 #define SL_TRNG_ERR_CONDITIONING_TEST_FAILED ((int)SL_TRNG_ERR_BASE | 0x00000001)
AnnaBridge 145:64910690c574 59
AnnaBridge 145:64910690c574 60 /** No data received in the TRNG FIFO. */
AnnaBridge 145:64910690c574 61 #define SL_TRNG_ERR_NO_DATA ((int)SL_TRNG_ERR_BASE | 0x00000002)
AnnaBridge 145:64910690c574 62
AnnaBridge 145:64910690c574 63 /** Repetition Count test failed. The repetition count test fails when the
AnnaBridge 145:64910690c574 64 * TRNG detects that the output become "stuck" on a single value for a long
AnnaBridge 145:64910690c574 65 * period of time. The repetition count test is described in NIST-800-90B.
AnnaBridge 145:64910690c574 66 *
AnnaBridge 145:64910690c574 67 * If an application detects this error then the TRNG should be reset. The
AnnaBridge 145:64910690c574 68 * repetition count test is always enabled. */
AnnaBridge 145:64910690c574 69 #define SL_TRNG_ERR_REPETITION_COUNT_TEST_FAILED ((int)SL_TRNG_ERR_BASE | 0x00000003)
AnnaBridge 145:64910690c574 70
AnnaBridge 145:64910690c574 71 /** Adaptive Proportion test over 64 samples failed. The adaptive proportion
AnnaBridge 145:64910690c574 72 * test is designed to detect a large loss of entropy that might occur as a
AnnaBridge 145:64910690c574 73 * result of some physical failure or environmental change affecting the
AnnaBridge 145:64910690c574 74 * TRNG.
AnnaBridge 145:64910690c574 75 *
AnnaBridge 145:64910690c574 76 * The test will fail when a 2 bit sample from the TRNG is repeated an
AnnaBridge 145:64910690c574 77 * unusual amount of times within a window of 64 bits. The adaptive
AnnaBridge 145:64910690c574 78 * proportion test is further described in NIST-800-90B.
AnnaBridge 145:64910690c574 79 *
AnnaBridge 145:64910690c574 80 * If an application detects this error then the TRNG should be reset. The
AnnaBridge 145:64910690c574 81 * adaptive proportion test over 64 samples is always enabled. */
AnnaBridge 145:64910690c574 82 #define SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_64_FAILED ((int)SL_TRNG_ERR_BASE | 0x00000004)
AnnaBridge 145:64910690c574 83
AnnaBridge 145:64910690c574 84 /** Adaptive Proportion test over 4096 samples failed. The adaptive proportion
AnnaBridge 145:64910690c574 85 * test is designed to detect a large loss of entropy that might occur as a
AnnaBridge 145:64910690c574 86 * result of some physical failure or environmental change affecting the
AnnaBridge 145:64910690c574 87 * TRNG.
AnnaBridge 145:64910690c574 88 *
AnnaBridge 145:64910690c574 89 * The test will fail when a 2 bit sample from the TRNG is repeated an
AnnaBridge 145:64910690c574 90 * unusual amount of times within a window of 4096 bits. The adaptive
AnnaBridge 145:64910690c574 91 * proportion test is further described in NIST-800-90B.
AnnaBridge 145:64910690c574 92 *
AnnaBridge 145:64910690c574 93 * If an application detects this error then the TRNG should be reset. The
AnnaBridge 145:64910690c574 94 * adaptive proportion test over 4096 samples is always enabled. */
AnnaBridge 145:64910690c574 95 #define SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_4096_FAILED ((int)SL_TRNG_ERR_BASE | 0x00000005)
AnnaBridge 145:64910690c574 96
AnnaBridge 145:64910690c574 97 /** AIS31 test noise alarm. The AIS31 test is designed to monitor and verify
AnnaBridge 145:64910690c574 98 * the statistical distribution of the random numbers from the TRNG. The test
AnnaBridge 145:64910690c574 99 * performs 512 consecutive 128 bit X^2 calculations with 4 bit words. The
AnnaBridge 145:64910690c574 100 * details of the AIS31 test can be found in the AIS31 specification.
AnnaBridge 145:64910690c574 101 *
AnnaBridge 145:64910690c574 102 * The test will fail when an unusual statistical distribution of the TRNG
AnnaBridge 145:64910690c574 103 * output is found.
AnnaBridge 145:64910690c574 104 *
AnnaBridge 145:64910690c574 105 * If an application detects this error then the TRNG should be reset. The
AnnaBridge 145:64910690c574 106 * AIS31 test is always enabled. */
AnnaBridge 145:64910690c574 107 #define SL_TRNG_ERR_NOISE_ALARM ((int)SL_TRNG_ERR_BASE | 0x00000006)
AnnaBridge 145:64910690c574 108
AnnaBridge 145:64910690c574 109 /** AIS31 test Preliminary Noise alarm. The preliminary noise alarms generated
AnnaBridge 145:64910690c574 110 * from the same AIS31 test that generates \ref SL_TRNG_ERR_NOISE_ALARM.
AnnaBridge 145:64910690c574 111 * The difference between a preliminary noise alarm and a noise alarm is the
AnnaBridge 145:64910690c574 112 * severity and the expected frequency. A preliminary noise alarm will happen
AnnaBridge 145:64910690c574 113 * more frequently than a noise alarm, and a preliminary noise alarm is not
AnnaBridge 145:64910690c574 114 * considered critical. The preliminary noise alarm is not uncommon and should
AnnaBridge 145:64910690c574 115 * be expected from time to time when reading data from the TRNG.
AnnaBridge 145:64910690c574 116 *
AnnaBridge 145:64910690c574 117 * If an application detects a preliminary noise alarm then the recommended
AnnaBridge 145:64910690c574 118 * action is to flush the TRNG FIFO, or reset the TRNG. */
AnnaBridge 145:64910690c574 119 #define SL_TRNG_ERR_PRELIMINARY_NOISE_ALARM ((int)SL_TRNG_ERR_BASE | 0x00000007)
AnnaBridge 145:64910690c574 120
AnnaBridge 145:64910690c574 121 #if defined(TRNG_PRESENT)
AnnaBridge 145:64910690c574 122
AnnaBridge 145:64910690c574 123 /**
AnnaBridge 145:64910690c574 124 * \brief Initialize TRNG context
AnnaBridge 145:64910690c574 125 *
AnnaBridge 145:64910690c574 126 * \details This function will enable the TRNG device by starting
AnnaBridge 145:64910690c574 127 * the device's clock, initializing the control register, perform
AnnaBridge 145:64910690c574 128 * soft reset and wait until data is available in the FIFO.
AnnaBridge 145:64910690c574 129 *
AnnaBridge 145:64910690c574 130 * \param ctx TRNG device to be initialized
AnnaBridge 145:64910690c574 131 */
AnnaBridge 145:64910690c574 132 void sl_trng_init( TRNG_TypeDef *ctx );
AnnaBridge 145:64910690c574 133
AnnaBridge 145:64910690c574 134 /**
AnnaBridge 145:64910690c574 135 * \brief Free TRNG context
AnnaBridge 145:64910690c574 136 *
AnnaBridge 145:64910690c574 137 * \details This function will disable the TRNG peripheral by stopping
AnnaBridge 145:64910690c574 138 * the TRNG's clock.
AnnaBridge 145:64910690c574 139 *
AnnaBridge 145:64910690c574 140 * \param ctx TRNG device to be released
AnnaBridge 145:64910690c574 141 */
AnnaBridge 145:64910690c574 142 void sl_trng_free( TRNG_TypeDef *ctx );
AnnaBridge 145:64910690c574 143
AnnaBridge 145:64910690c574 144 /**
AnnaBridge 145:64910690c574 145 * \brief Set the TRNG conditioning key
AnnaBridge 145:64910690c574 146 *
AnnaBridge 145:64910690c574 147 * \param ctx TRNG device
AnnaBridge 145:64910690c574 148 * \param key 128-bit AES key
AnnaBridge 145:64910690c574 149 *
AnnaBridge 145:64910690c574 150 * \return
AnnaBridge 145:64910690c574 151 * 0 if success. Error code if failure.
AnnaBridge 145:64910690c574 152 */
AnnaBridge 145:64910690c574 153 int sl_trng_set_key( TRNG_TypeDef *ctx, const unsigned char *key );
AnnaBridge 145:64910690c574 154
AnnaBridge 145:64910690c574 155 /**
AnnaBridge 145:64910690c574 156 * \brief Poll for entropy data
AnnaBridge 145:64910690c574 157 *
AnnaBridge 145:64910690c574 158 * \details This function will read available random data from the TRNG
AnnaBridge 145:64910690c574 159 * FIFO and place it into the output buffer. The len parameter
AnnaBridge 145:64910690c574 160 * tells this function the maximum number of bytes to read.
AnnaBridge 145:64910690c574 161 *
AnnaBridge 145:64910690c574 162 * Note that the number of bytes read from the TRNG might differ
AnnaBridge 145:64910690c574 163 * from the number of bytes requested. If any alarms are signaled
AnnaBridge 145:64910690c574 164 * or the TRNG FIFO is empty then this function will return early.
AnnaBridge 145:64910690c574 165 *
AnnaBridge 145:64910690c574 166 * The return value should be used to see if the operation was
AnnaBridge 145:64910690c574 167 * successful of if an alarm was encountered while reading the
AnnaBridge 145:64910690c574 168 * FIFO. The content of the olen parameter can be used to check
AnnaBridge 145:64910690c574 169 * how many bytes were actually read.
AnnaBridge 145:64910690c574 170 *
AnnaBridge 145:64910690c574 171 * \param ctx TRNG context
AnnaBridge 145:64910690c574 172 * \param output Buffer to fill with data from the TRNG
AnnaBridge 145:64910690c574 173 * \param len Maximum number of bytes to fill in output buffer.
AnnaBridge 145:64910690c574 174 * \param olen The actual amount of bytes put into the buffer (Can be 0)
AnnaBridge 145:64910690c574 175 *
AnnaBridge 145:64910690c574 176 * \return \li 0 if no critical failures occurred,
AnnaBridge 145:64910690c574 177 * \li SL_TRNG_ERR_PRELIMINARY_NOISE_ALARM if a AIS31
AnnaBridge 145:64910690c574 178 * preliminary noise alarm was detected while reading the FIFO,
AnnaBridge 145:64910690c574 179 * \li SL_TRNG_ERR_NOISE_ALARM if an AIS31 noise alarm
AnnaBridge 145:64910690c574 180 * was detected.
AnnaBridge 145:64910690c574 181 * \li SL_TRNG_ERR_REPETITION_COUNT_TEST_FAILED if the
AnnaBridge 145:64910690c574 182 * repetition count test failed while reading the FIFO.
AnnaBridge 145:64910690c574 183 * \li SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_64_FAILED if the
AnnaBridge 145:64910690c574 184 * adaptive proportion test over 64 samples failed while reading
AnnaBridge 145:64910690c574 185 * the FIFO.
AnnaBridge 145:64910690c574 186 * \li SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_4096_FAILED if
AnnaBridge 145:64910690c574 187 * the adaptive proportion test over 4096 samples failed while
AnnaBridge 145:64910690c574 188 * reading from the FIFO.
AnnaBridge 145:64910690c574 189 */
AnnaBridge 145:64910690c574 190 int sl_trng_poll( TRNG_TypeDef *ctx,
AnnaBridge 145:64910690c574 191 unsigned char *output,
AnnaBridge 145:64910690c574 192 size_t len,
AnnaBridge 145:64910690c574 193 size_t *olen );
AnnaBridge 145:64910690c574 194
AnnaBridge 145:64910690c574 195 /**
AnnaBridge 145:64910690c574 196 * \brief Execute TRNG soft reset
AnnaBridge 145:64910690c574 197 *
AnnaBridge 145:64910690c574 198 * \details This function performs a TRNG soft reset. The TRNG soft
AnnaBridge 145:64910690c574 199 * reset can be used to clear error conditions such as Noise
AnnaBridge 145:64910690c574 200 * Alarms, etc.
AnnaBridge 145:64910690c574 201 *
AnnaBridge 145:64910690c574 202 * \param ctx TRNG device
AnnaBridge 145:64910690c574 203 */
AnnaBridge 145:64910690c574 204 void sl_trng_soft_reset( TRNG_TypeDef *ctx );
AnnaBridge 145:64910690c574 205
AnnaBridge 145:64910690c574 206 #endif /* TRNG_PRESENT */
AnnaBridge 145:64910690c574 207
AnnaBridge 145:64910690c574 208 /** \} (end addtogroup sl_crypto_trng) */
AnnaBridge 145:64910690c574 209
AnnaBridge 145:64910690c574 210 #endif /* SL_TRNG_H */