takashi kadono / Mbed OS Nucleo446_SSD1331

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   ssd1331

mbed-os/features/device_key/README.md@0:8fdf9a60065b, 2018-10-10 (annotated)

Committer:
kadonotakashi
Date:
Wed Oct 10 00:33:53 2018 +0000
Revision:
0:8fdf9a60065b
how to make mbed librry

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kadonotakashi 0:8fdf9a60065b 1 ## DeviceKey
kadonotakashi 0:8fdf9a60065b 2
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 4
kadonotakashi 0:8fdf9a60065b 5 We have implemented DeviceKey according to NIST SP 800-108, section "KDF in Counter Mode", with AES-CMAC as the pseudorandom function.
kadonotakashi 0:8fdf9a60065b 6
kadonotakashi 0:8fdf9a60065b 7 ### Root of Trust
kadonotakashi 0:8fdf9a60065b 8
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 10
kadonotakashi 0:8fdf9a60065b 11 The characteristics required by this root of trust are:
kadonotakashi 0:8fdf9a60065b 12
kadonotakashi 0:8fdf9a60065b 13 - It must be unique per device.
kadonotakashi 0:8fdf9a60065b 14 - It must be difficult to guess.
kadonotakashi 0:8fdf9a60065b 15 - It must be at least 128 bits.
kadonotakashi 0:8fdf9a60065b 16 - It must be kept secret.
kadonotakashi 0:8fdf9a60065b 17
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 19
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 21
kadonotakashi 0:8fdf9a60065b 22 ### Key derivation API
kadonotakashi 0:8fdf9a60065b 23
kadonotakashi 0:8fdf9a60065b 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.
kadonotakashi 0:8fdf9a60065b 25
kadonotakashi 0:8fdf9a60065b 26 #### Root of Trust Injection API
kadonotakashi 0:8fdf9a60065b 27
kadonotakashi 0:8fdf9a60065b 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).
kadonotakashi 0:8fdf9a60065b 29
kadonotakashi 0:8fdf9a60065b 30 #### Using DeviceKey
kadonotakashi 0:8fdf9a60065b 31
kadonotakashi 0:8fdf9a60065b 32 DeviceKey is a singleton class, meaning that the system can have only a single instance of it.
kadonotakashi 0:8fdf9a60065b 33
kadonotakashi 0:8fdf9a60065b 34 To instantiate DeviceKey, you need to call its `get_instance` member function as following:
kadonotakashi 0:8fdf9a60065b 35
kadonotakashi 0:8fdf9a60065b 36 ```c++
kadonotakashi 0:8fdf9a60065b 37 DeviceKey &deviceKey = DeviceKey::get_instance();
kadonotakashi 0:8fdf9a60065b 38 ```
kadonotakashi 0:8fdf9a60065b 39
kadonotakashi 0:8fdf9a60065b 40 #### Testing DeviceKey
kadonotakashi 0:8fdf9a60065b 41
kadonotakashi 0:8fdf9a60065b 42 Run the DeviceKey functionality test with the `mbed` command as follows:
kadonotakashi 0:8fdf9a60065b 43
kadonotakashi 0:8fdf9a60065b 44 ```
kadonotakashi 0:8fdf9a60065b 45 ```mbed test -n features-device_key-tests-device_key-functionality```
kadonotakashi 0:8fdf9a60065b 46 ```