spinel: Added feature for true random number generation (#1098)

Sometimes the host processor doesn't have a good way to generate
high-quality random numbers suitable for cryptographic use. However,
the NCP often has such capability. This Spinel feature allows
the host processor to fetch high-quality random numbers from a
TRNG that may be present on the NCP.

doc/spinel-protocol-src/draft-spinel-protocol.md.in

@@ -322,6 +322,8 @@ is meaningless.
 
 {{spinel-feature-gpio.md}}
 
+{{spinel-feature-trng.md}}
+
 {{spinel-security-considerations.md}}
 
 {backmatter}

doc/spinel-protocol-src/spinel-feature-trng.md

@@ -0,0 +1,77 @@
+# Feature: True Random Number Generation {#feature-trng}
+
+This feature allows the host to have access to any strong hardware
+random number generator that might be present on the NCP, for things
+like key generation or seeding PRNGs.
+
+Support for this feature can be determined by the presence of `CAP_TRNG`.
+
+Note well that implementing a cryptographically-strong software-based true
+random number generator (that is impervious to things like temperature
+changes, manufacturing differences across devices, or unexpected output
+correlations) is non-trivial without a well-designed, dedicated hardware
+random number generator. Implementors who have little or no experience in
+this area are encouraged to not advertise this capability.
+
+## Properties ##
+
+### PROP 4101: PROP_TRNG_32 ###
+
+*   Argument-Encoding: `L`
+*   Type: Read-Only
+
+Fetching this property returns a strong random 32-bit integer that is suitable
+for use as a PRNG seed or for cryptographic use.
+
+While the exact mechanism behind the calculation of this value is
+implementation-specific, the implementation must satisfy the following
+requirements:
+
+* Data representing at least 32 bits of fresh entropy (extracted from the
+  primary entropy source) MUST be consumed by the calculation of each query.
+* Each of the 32 bits returned MUST be free of bias and have no statistical
+  correlation to any part of the raw data used for the calculation of any
+  query.
+
+Support for this property is REQUIRED if `CAP_TRNG` is included in the
+device capabilities.
+
+### PROP 4102: PROP_TRNG_128 ###
+
+*   Argument-Encoding: `D`
+*   Type: Read-Only
+
+Fetching this property returns 16 bytes of strong random data suitable for
+direct cryptographic use without further processing(For example, as an
+AES key).
+
+While the exact mechanism behind the calculation of this value is
+implementation-specific, the implementation must satisfy the following
+requirements:
+
+* Data representing at least 128 bits of fresh entropy (extracted from the
+  primary entropy source) MUST be consumed by the calculation of each query.
+* Each of the 128 bits returned MUST be free of bias and have no statistical
+  correlation to any part of the raw data used for the calculation of any
+  query.
+
+Support for this property is REQUIRED if `CAP_TRNG` is included in the
+device capabilities.
+
+### PROP 4103: PROP_TRNG_RAW_32 ###
+
+*   Argument-Encoding: `D`
+*   Type: Read-Only
+
+This property is primarily used to diagnose and debug the behavior
+of the entropy source used for strong random number generation.
+
+When queried, returns the raw output from the entropy source used to
+generate `PROP_TRNG_32`, prior to any reduction/whitening and/or mixing
+with prior state.
+
+The length of the returned buffer is implementation specific and should be
+expected to be non-deterministic.
+
+Support for this property is RECOMMENDED if `CAP_TRNG` is included in the
+device capabilities.

doc/spinel-protocol-src/spinel-prop-core.md

@@ -132,6 +132,7 @@ Currently defined values are:
  * 7: `CAP_PEEK_POKE`: PEEK/POKE debugging commands.
  * 8: `CAP_WRITABLE_RAW_STREAM`: `PROP_STREAM_RAW` is writable.
  * 9: `CAP_GPIO`: Support for GPIO access. See (#feature-gpio-access).
+ * 10: `CAP_TRNG`: Support for true random number generation. See (#feature-trng).
  * 16: `CAP_802_15_4_2003`
  * 17: `CAP_802_15_4_2006`
  * 18: `CAP_802_15_4_2011`

src/ncp/spinel.h

@@ -310,6 +310,7 @@ enum
 
     SPINEL_CAP_WRITABLE_RAW_STREAM   = 8,
     SPINEL_CAP_GPIO                  = 9,
+    SPINEL_CAP_TRNG                  = 10,
 
     SPINEL_CAP_802_15_4__BEGIN        = 16,
     SPINEL_CAP_802_15_4_2003          = (SPINEL_CAP_802_15_4__BEGIN + 0),
@@ -478,6 +479,15 @@ typedef enum
      */
     SPINEL_PROP_GPIO_STATE_CLEAR        = SPINEL_PROP_BASE_EXT__BEGIN + 4,
 
+    /// 32-bit random number from TRNG, ready-to-use.
+    SPINEL_PROP_TRNG_32                 = SPINEL_PROP_BASE_EXT__BEGIN + 5,
+
+    /// 16 random bytes from TRNG, ready-to-use.
+    SPINEL_PROP_TRNG_128                = SPINEL_PROP_BASE_EXT__BEGIN + 6,
+
+    /// Raw samples from TRNG entropy source representing 32 bits of entropy.
+    SPINEL_PROP_TRNG_RAW_32             = SPINEL_PROP_BASE_EXT__BEGIN + 7,
+
     SPINEL_PROP_BASE_EXT__END           = 0x1100,
 
     SPINEL_PROP_PHY__BEGIN              = 0x20,