From fd9fcf53fe45a077e7a48b3dd148ba3319a91774 Mon Sep 17 00:00:00 2001 From: Robert Quattlebaum Date: Wed, 21 Dec 2016 12:38:25 -0800 Subject: [PATCH] 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. --- .../draft-spinel-protocol.md.in | 2 + .../spinel-feature-trng.md | 77 +++++++++++++++++++ doc/spinel-protocol-src/spinel-prop-core.md | 1 + src/ncp/spinel.h | 10 +++ 4 files changed, 90 insertions(+) create mode 100644 doc/spinel-protocol-src/spinel-feature-trng.md diff --git a/doc/spinel-protocol-src/draft-spinel-protocol.md.in b/doc/spinel-protocol-src/draft-spinel-protocol.md.in index 228e5d46b..fcf2c3864 100644 --- a/doc/spinel-protocol-src/draft-spinel-protocol.md.in +++ b/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} diff --git a/doc/spinel-protocol-src/spinel-feature-trng.md b/doc/spinel-protocol-src/spinel-feature-trng.md new file mode 100644 index 000000000..c310b43cd --- /dev/null +++ b/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. diff --git a/doc/spinel-protocol-src/spinel-prop-core.md b/doc/spinel-protocol-src/spinel-prop-core.md index 7662d7c68..60d122ec0 100644 --- a/doc/spinel-protocol-src/spinel-prop-core.md +++ b/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` diff --git a/src/ncp/spinel.h b/src/ncp/spinel.h index 289c57fa6..0fb327569 100644 --- a/src/ncp/spinel.h +++ b/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,