Merge pull request #1244 from tymoteuszblochmobica/rot

Update DeviceKey document after root of trust refactoring

Author: Amanda Butler

docs/api/security/Devicekey.md

@@ -19,31 +19,62 @@ The characteristics required by this root of trust are:
 
 The DeviceKey feature keeps the root of trust key in internal storage, using the KVStore component. Internal storage provides protection from external physical attacks to the device.
 
-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.
+The root of trust must be created before its first use. Otherwise, the key derivation API fails.
 
 ## Key derivation API
 
 `generate_derived_key`: This API generates a new key based on an array of data ([salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) the caller provides. A single salt value always generates the same key, so if you need a new key, you must use a new salt value. The salt can have any value - array, string and so on.
 
-The generated keys can be 128 or 256 bits in length.
+The generated keys can be 128b or 256b in length.
 
-### Root of Trust Injection API
+### Root of Trust generation API
 
-`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).
+DeviceKey class needs root of trust ready to use before the derivation API's first call. There are two options to achieve this:
+
+- Create a device key using a built-in random number generator.
+- Manually fill the device key data array.
+
+Both cases requires injecting this key data to the KVStore reserved area.
+
+When `DEVICE_TRNG` is defined, the device supports a random number generator, and you may generate the key by calling `generate_root_of_trust()`. The call succeeds only if the key does not already exist. You can't change the existing key.
+
+```c++ NOCI
+int status = DeviceKey::get_instance().generate_root_of_trust();
+if(status == DEVICEKEY_SUCCESS) {
+    //success
+} else {
+   //error
+}
+```
+
+If `DEVICE_TRNG` is not defined, the key buffer must be filled manually by calling `device_inject_root_of_trust()`. The example below shows an injection of a dummy key:
+
+```c++ NOCI
+uint32_t key[DEVICE_KEY_32BYTE / sizeof(uint32_t)];
+memcpy(key, "12345678123456781234567812345678", DEVICE_KEY_32BYTE);
+int size = DEVICE_KEY_32BYTE;
+
+int status = DeviceKey::get_instance().device_inject_root_of_trust(key, size);
+if(status == DEVICEKEY_SUCCESS) {
+    //success
+} else {
+    //error
+}
+``` 
 
 ### Using DeviceKey
 
-DeviceKey is a singleton class, meaning that the system can have only a single instance of it.
+DeviceKey is a singleton class, meaning the system can have only a single instance of it.
 
-To instantiate DeviceKey, you need to call its `get_instance` member function as following:
+To instantiate DeviceKey, call its `get_instance` member function:
 
 ```c++ TODO
     DeviceKey &deviceKey = DeviceKey::get_instance();
 ```
 
 ### Testing DeviceKey
 
-Run the DeviceKey functionality test with the `mbed` command as following:
+Run the DeviceKey functionality test with the `mbed`:
 
 ```
     mbed test -n features-device_key-tests-device_key-functionality