mbed official / mbed-dev

mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

targets/TARGET_Silicon_Labs/TARGET_EFM32/trng/sl_trng.h@189:f392fc9709a3, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 22:31:08 2019 +0000
Revision:
189:f392fc9709a3
Parent:
167:e84263d55307 
mbed library release version 165

Who changed what in which revision?

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