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_EFM32ZG_STK3200/TOOLCHAIN_ARM_MICRO/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?
User | Revision | Line number | New 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 */ |