Skip to content

Commit ab7f37b

Browse files
Update DeviceKey document after root of trust refactoring.
1 parent c288587 commit ab7f37b

File tree

1 file changed

+37
-3
lines changed

1 file changed

+37
-3
lines changed

docs/api/security/Devicekey.md

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,51 @@ The characteristics required by this root of trust are:
1919

2020
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.
2121

22-
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.
22+
The root of trust must be created before its first use. Otherwise key derivation API will fail.
2323

2424
## Key derivation API
2525

2626
`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.
2727

2828
The generated keys can be 128 or 256 bits in length.
2929

30-
### Root of Trust Injection API
30+
### Root of Trust generation API
3131

32-
`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).
32+
DeviceKey class needs ROT ready to use before derivation API first call. There are two options to achieve it:
33+
34+
35+
- Create device key using built-in random number generator
36+
37+
- Manually fill device key data array
38+
39+
Both cases requires injecting this key data to kvstore reserved area.
40+
41+
The first way is used when device supports random number generator - ` DEVICE_TRNG` is defined.
42+
Then `generate_root_of_trust` must be called only once.
43+
44+
```c++ NOCI
45+
int status = DeviceKey::get_instance().generate_root_of_trust();
46+
if(status == DEVICEKEY_SUCCESS) {
47+
//success
48+
} else {
49+
//error
50+
}
51+
```
52+
53+
If `DEVICE_TRNG` is not defined then key buffer must be filled manually and followed by `device_inject_root_of_trust` call. The example below shows an injection of a dummy key.
54+
55+
```c++ NOCI
56+
uint32_t key[DEVICE_KEY_32BYTE / sizeof(uint32_t)];
57+
memcpy(key, "12345678123456781234567812345678", DEVICE_KEY_32BYTE);
58+
int size = DEVICE_KEY_32BYTE;
59+
60+
int status = DeviceKey::get_instance().device_inject_root_of_trust(key, size);
61+
if(status == DEVICEKEY_SUCCESS) {
62+
//success
63+
} else {
64+
//error
65+
}
66+
```
3367
3468
### Using DeviceKey
3569

0 commit comments

Comments
 (0)