Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

features/device_key/README.md@0:5b88d5760320, 2019-12-17 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 17 23:23:45 2019 +0000
Revision:
0:5b88d5760320
Child:
1:9db0e321a9f4
mbed-os5 only for TYBLE16

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kenjiArai 0:5b88d5760320 1 ## DeviceKey
kenjiArai 0:5b88d5760320 2
kenjiArai 0:5b88d5760320 3 DeviceKey is a mechanism that implements key derivation from a root of trust key. The DeviceKey mechanism generates symmetric keys that security features need. You can use these keys for encryption, authentication and more. The DeviceKey API allows key derivation without exposing the actual root of trust, to reduce the possibility of accidental exposure of the root of trust outside the device.
kenjiArai 0:5b88d5760320 4
kenjiArai 0:5b88d5760320 5 We have implemented DeviceKey according to NIST SP 800-108, section "KDF in Counter Mode", with AES-CMAC as the pseudorandom function.
kenjiArai 0:5b88d5760320 6
kenjiArai 0:5b88d5760320 7 ### Root of Trust
kenjiArai 0:5b88d5760320 8
kenjiArai 0:5b88d5760320 9 The root of trust key, which DeviceKey uses to derive additional keys, is generated using the hardware random generator if it exists, or using a key injected to the device in the production process.
kenjiArai 0:5b88d5760320 10
kenjiArai 0:5b88d5760320 11 The characteristics required by this root of trust are:
kenjiArai 0:5b88d5760320 12
kenjiArai 0:5b88d5760320 13 - It must be unique per device.
kenjiArai 0:5b88d5760320 14 - It must be difficult to guess.
kenjiArai 0:5b88d5760320 15 - It must be at least 128 bits.
kenjiArai 0:5b88d5760320 16 - It must be kept secret.
kenjiArai 0:5b88d5760320 17
kenjiArai 0:5b88d5760320 18 The DeviceKey feature keeps the root of trust key in internal storage, using the NVStore component. Internal storage provides protection from external physical attacks to the device.
kenjiArai 0:5b88d5760320 19
kenjiArai 0:5b88d5760320 20 The root of trust is generated at the first use of DeviceKey if the true random number generator is available in the device. If no true random number generator is available, you must pass the injected root of trust key to the DeviceKey before you call the key derivation API.
kenjiArai 0:5b88d5760320 21
kenjiArai 0:5b88d5760320 22 ### Key derivation API
kenjiArai 0:5b88d5760320 23
kenjiArai 0:5b88d5760320 24 `generate_derived_key`: This API generates a new key based on a string (salt) the caller provides. The same key is generated for the same salt. Generated keys can be 128 or 256 bits in length.
kenjiArai 0:5b88d5760320 25
kenjiArai 0:5b88d5760320 26 #### Root of Trust Injection API
kenjiArai 0:5b88d5760320 27
kenjiArai 0:5b88d5760320 28 `device_inject_root_of_trust`: You must call this API once in the lifecycle of the device, before any call to key derivation, if the device does not support True Random Number Generator (`DEVICE_TRNG` is not defined).
kenjiArai 0:5b88d5760320 29
kenjiArai 0:5b88d5760320 30 #### Using DeviceKey
kenjiArai 0:5b88d5760320 31
kenjiArai 0:5b88d5760320 32 DeviceKey is a singleton class, meaning that the system can have only a single instance of it.
kenjiArai 0:5b88d5760320 33
kenjiArai 0:5b88d5760320 34 To instantiate DeviceKey, you need to call its `get_instance` member function as following:
kenjiArai 0:5b88d5760320 35
kenjiArai 0:5b88d5760320 36 ```c++
kenjiArai 0:5b88d5760320 37 DeviceKey &deviceKey = DeviceKey::get_instance();
kenjiArai 0:5b88d5760320 38 ```
kenjiArai 0:5b88d5760320 39
kenjiArai 0:5b88d5760320 40 #### Testing DeviceKey
kenjiArai 0:5b88d5760320 41
kenjiArai 0:5b88d5760320 42 Run the DeviceKey functionality test with the `mbed` command as follows:
kenjiArai 0:5b88d5760320 43
kenjiArai 0:5b88d5760320 44 ```
kenjiArai 0:5b88d5760320 45 ```mbed test -n features-device_key-tests-device_key-functionality```
kenjiArai 0:5b88d5760320 46 ```