Diff: TARGET_EFM32GG_STK3700/TOOLCHAIN_IAR/sl_trng.h

Revision:

171:3a7713b1edbc

Parent:

145:64910690c574

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/TARGET_EFM32GG_STK3700/TOOLCHAIN_IAR/sl_trng.h	Thu Nov 08 11:45:42 2018 +0000
@@ -0,0 +1,210 @@
+/**
+ *  \file sl_trng.h
+ *
+ *  \brief True Random Number Generator (TRNG) driver for Silicon Labs devices
+ *
+ *  Copyright (C) 2016, Silicon Labs, http://www.silabs.com
+ *  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.
+ */
+#ifndef SL_TRNG_H
+#define SL_TRNG_H
+
+/***************************************************************************//**
+ * \addtogroup sl_crypto_trng Silicon Labs True Random Number Generator Plugin
+ * \brief True Random Number Generator (TRNG) driver for Silicon Labs devices.
+ *
+ * \details The EFR32xG12 and EFM32xG12 and newer Silicon Labs devices contains
+ * a True Random Number Generator (TRNG) peripheral. The TRNG is a
+ * non-deterministic random number generator based on a full hardware solution.
+ * The TRNG contains a 64 x 32-bit FIFO for reading out random numbers.
+ *
+ * The samples from entropy source within the TRNG are monitored permanently by
+ * 4 built in tests that detect issues with the noise source. The tests are
+ * specified in NIST-800-90B and AIS31. The tests that are always checking the
+ * entropy source are "Repetition Count Test", "Adaptive Proportion Test
+ * (64-sample window)", "Adaptive Proportion Test (4096-sample window)" and
+ * the "AIS31 Online Test".
+ *
+ * In addition the TRNG has options for running startup tests. When these tests
+ * are enabled the TRNG FIFO will not contains any data before all the startup
+ * tests have passed. There are 4 TRNG startup tests, 3 of the tests are
+ * specified in NIST-800-90B. These are the "Repetition Count Test", "Adaptive
+ * Proportion Test (64-sample window)" and "Adaptive Proportion Test
+ * (4096-sample window)". The last startup test is the AIS31 startup test. By
+ * default when using this driver all the startup tests are enabled.
+ *
+ * \{
+ ******************************************************************************/
+
+#include "em_device.h"
+#include <stddef.h>
+
+/* TRNG specific error codes: */
+#define SL_TRNG_ERR_BASE                                 (0xF100E000)
+
+/** Conditioning test failed. */
+#define SL_TRNG_ERR_CONDITIONING_TEST_FAILED             ((int)SL_TRNG_ERR_BASE | 0x00000001)
+
+/** No data received in the TRNG FIFO. */
+#define SL_TRNG_ERR_NO_DATA                              ((int)SL_TRNG_ERR_BASE | 0x00000002)
+
+/** Repetition Count test failed. The repetition count test fails when the
+ *  TRNG detects that the output become "stuck" on a single value for a long
+ *  period of time. The repetition count test is described in NIST-800-90B.
+ *
+ *  If an application detects this error then the TRNG should be reset. The
+ *  repetition count test is always enabled. */
+#define SL_TRNG_ERR_REPETITION_COUNT_TEST_FAILED         ((int)SL_TRNG_ERR_BASE | 0x00000003)
+
+/** Adaptive Proportion test over 64 samples failed. The adaptive proportion
+ *  test is designed to detect a large loss of entropy that might occur as a
+ *  result of some physical failure or environmental change affecting the
+ *  TRNG.
+ *
+ *  The test will fail when a 2 bit sample from the TRNG is repeated an
+ *  unusual amount of times within a window of 64 bits. The adaptive
+ *  proportion test is further described in NIST-800-90B.
+ *
+ *  If an application detects this error then the TRNG should be reset. The
+ *  adaptive proportion test over 64 samples is always enabled. */
+#define SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_64_FAILED   ((int)SL_TRNG_ERR_BASE | 0x00000004)
+
+/** Adaptive Proportion test over 4096 samples failed. The adaptive proportion
+ *  test is designed to detect a large loss of entropy that might occur as a
+ *  result of some physical failure or environmental change affecting the
+ *  TRNG.
+ *
+ *  The test will fail when a 2 bit sample from the TRNG is repeated an
+ *  unusual amount of times within a window of 4096 bits. The adaptive
+ *  proportion test is further described in NIST-800-90B.
+ *
+ *  If an application detects this error then the TRNG should be reset. The
+ *  adaptive proportion test over 4096 samples is always enabled. */
+#define SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_4096_FAILED ((int)SL_TRNG_ERR_BASE | 0x00000005)
+
+/** AIS31 test noise alarm. The AIS31 test is designed to monitor and verify
+ *  the statistical distribution of the random numbers from the TRNG. The test
+ *  performs 512 consecutive 128 bit X^2 calculations with 4 bit words. The
+ *  details of the AIS31 test can be found in the AIS31 specification.
+ *
+ *  The test will fail when an unusual statistical distribution of the TRNG
+ *  output is found.
+ *
+ *  If an application detects this error then the TRNG should be reset. The
+ *  AIS31 test is always enabled. */
+#define SL_TRNG_ERR_NOISE_ALARM                          ((int)SL_TRNG_ERR_BASE | 0x00000006)
+
+/** AIS31 test Preliminary Noise alarm. The preliminary noise alarms generated
+ *  from the same AIS31 test that generates \ref SL_TRNG_ERR_NOISE_ALARM.
+ *  The difference between a preliminary noise alarm and a noise alarm is the
+ *  severity and the expected frequency. A preliminary noise alarm will happen
+ *  more frequently than a noise alarm, and a preliminary noise alarm is not
+ *  considered critical. The preliminary noise alarm is not uncommon and should
+ *  be expected from time to time when reading data from the TRNG.
+ *
+ *  If an application detects a preliminary noise alarm then the recommended
+ *  action is to flush the TRNG FIFO, or reset the TRNG. */
+#define SL_TRNG_ERR_PRELIMINARY_NOISE_ALARM              ((int)SL_TRNG_ERR_BASE | 0x00000007)
+
+#if defined(TRNG_PRESENT)
+
+/**
+ * \brief          Initialize TRNG context
+ *
+ * \details        This function will enable the TRNG device by starting
+ *                 the device's clock, initializing the control register, perform
+ *                 soft reset and wait until data is available in the FIFO.
+ *
+ * \param ctx      TRNG device to be initialized
+ */
+void sl_trng_init( TRNG_TypeDef *ctx );
+
+/**
+ * \brief          Free TRNG context
+ *
+ * \details        This function will disable the TRNG peripheral by stopping
+ *                 the TRNG's clock.
+ *
+ * \param ctx      TRNG device to be released
+ */
+void sl_trng_free( TRNG_TypeDef *ctx );
+
+/**
+ * \brief          Set the TRNG conditioning key
+ *
+ * \param ctx      TRNG device
+ * \param key      128-bit AES key
+ *  
+ * \return
+ *   0 if success. Error code if failure.
+ */
+int sl_trng_set_key( TRNG_TypeDef *ctx, const unsigned char *key );
+
+/**
+ * \brief           Poll for entropy data
+ *
+ * \details         This function will read available random data from the TRNG
+ *                  FIFO and place it into the output buffer. The len parameter
+ *                  tells this function the maximum number of bytes to read.
+ *
+ *                  Note that the number of bytes read from the TRNG might differ
+ *                  from the number of bytes requested. If any alarms are signaled
+ *                  or the TRNG FIFO is empty then this function will return early.
+ *
+ *                  The return value should be used to see if the operation was
+ *                  successful of if an alarm was encountered while reading the
+ *                  FIFO. The content of the olen parameter can be used to check
+ *                  how many bytes were actually read.
+ *
+ * \param ctx       TRNG context
+ * \param output    Buffer to fill with data from the TRNG
+ * \param len       Maximum number of bytes to fill in output buffer.
+ * \param olen      The actual amount of bytes put into the buffer (Can be 0)
+ *
+ * \return          \li 0 if no critical failures occurred,
+ *                  \li SL_TRNG_ERR_PRELIMINARY_NOISE_ALARM if a AIS31
+ *                  preliminary noise alarm was detected while reading the FIFO,
+ *                  \li SL_TRNG_ERR_NOISE_ALARM if an AIS31 noise alarm
+ *                  was detected.
+ *                  \li SL_TRNG_ERR_REPETITION_COUNT_TEST_FAILED if the
+ *                  repetition count test failed while reading the FIFO.
+ *                  \li SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_64_FAILED if the
+ *                  adaptive proportion test over 64 samples failed while reading
+ *                  the FIFO.
+ *                  \li SL_TRNG_ERR_ADAPTIVE_PROPORTION_TEST_4096_FAILED if
+ *                  the adaptive proportion test over 4096 samples failed while
+ *                  reading from the FIFO.
+ */
+int sl_trng_poll( TRNG_TypeDef *ctx,
+                  unsigned char *output,
+                  size_t len,
+                  size_t *olen );
+
+/**
+ * \brief           Execute TRNG soft reset
+ *
+ * \details         This function performs a TRNG soft reset. The TRNG soft
+ *                  reset can be used to clear error conditions such as Noise
+ *                  Alarms, etc.
+ *
+ * \param ctx       TRNG device
+ */
+void sl_trng_soft_reset( TRNG_TypeDef *ctx );
+
+#endif /* TRNG_PRESENT */
+
+/** \} (end addtogroup sl_crypto_trng) */
+
+#endif /* SL_TRNG_H */