Skip to content

Commit 616da8f

Browse files
author
deepikabhavnani
committed
DeviceKey page update
1 parent 829ee1a commit 616da8f

File tree

1 file changed

+7
-147
lines changed

1 file changed

+7
-147
lines changed

‎docs/api/drivers/Devicekey.md

Lines changed: 7 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
## DeviceKey
22

3-
<span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_device_key.png)<span>DeviceKey class hierarchy</span></span>
3+
#### DeviceKey class hierarchy
4+
5+
<span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_device_key.png)<span></span>
46

57
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.
68

@@ -23,15 +25,15 @@ The root of trust is generated at the first use of DeviceKey if the true random
2325

2426
### Key derivation API
2527

26-
`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 be have any value - array, string and so on.
28+
`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.
2729

2830
The generated keys can be 128 or 256 bits in length.
2931

3032
#### Root of Trust Injection API
3133

3234
`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).
3335

34-
#### Using DeviceKey
36+
#### Using DeviceKey
3537

3638
DeviceKey is a singleton class, meaning that the system can have only a single instance of it.
3739

@@ -45,7 +47,7 @@ To instantiate DeviceKey, you need to call its `get_instance` member function as
4547

4648
Run the DeviceKey functionality test with the `mbed` command as following:
4749

48-
```
50+
```
4951
mbed test -n features-device_key-tests-device_key-functionality
5052
```
5153

@@ -55,146 +57,4 @@ Run the DeviceKey functionality test with the `mbed` command as following:
5557

5658
### DeviceKey example
5759

58-
```
59-
/*
60-
* Copyright (c) 2018 ARM Limited. All rights reserved.
61-
* SPDX-License-Identifier: Apache-2.0
62-
* Licensed under the Apache License, Version 2.0 (the License); you may
63-
* not use this file except in compliance with the License.
64-
* You may obtain a copy of the License at
65-
*
66-
* http://www.apache.org/licenses/LICENSE-2.0
67-
*
68-
* Unless required by applicable law or agreed to in writing, software
69-
* distributed under the License is distributed on an AS IS BASIS, WITHOUT
70-
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
71-
* See the License for the specific language governing permissions and
72-
* limitations under the License.
73-
*/
74-
75-
#include "mbed.h"
76-
#include "DeviceKey.h"
77-
78-
//print a unsigned char buffer in hex format
79-
void print_buffer(unsigned char *buf, size_t size)
80-
{
81-
for (size_t i = 0; i < size; i++) {
82-
printf("%02X", buf[i]);
83-
}
84-
}
85-
86-
//Injection of a dummy key when there is no TRNG
87-
int inject_rot_key()
88-
{
89-
uint32_t key[DEVICE_KEY_16BYTE / sizeof(uint32_t)];
90-
91-
memset(key, 0, DEVICE_KEY_16BYTE);
92-
memcpy(key, "ABCDEF1234567890", DEVICE_KEY_16BYTE);
93-
int size = DEVICE_KEY_16BYTE;
94-
DeviceKey& devkey = DeviceKey::get_instance();
95-
return devkey.device_inject_root_of_trust(key, size);
96-
}
97-
98-
// Entry point for the example
99-
int main()
100-
{
101-
unsigned char derive_key1 [DEVICE_KEY_32BYTE];
102-
unsigned char derive_key2 [DEVICE_KEY_32BYTE];
103-
unsigned char salt1[] = "SALT1 ----- SALT1 ------ SALT1";
104-
unsigned char salt2[] = "SALT2 ----- SALT2 ------ SALT2";
105-
int ret = DEVICEKEY_SUCCESS;
106-
107-
printf("\n--- Mbed OS DeviceKey example ---\n");
108-
109-
//DeviceKey is a singleton
110-
DeviceKey& devkey = DeviceKey::get_instance();
111-
112-
#if not defined(DEVICE_TRNG)
113-
114-
//If TRNG is not available it is a must to inject the ROT before the first call to derive key method.
115-
printf("\n--- No TRNG support for this device. injecting ROT. ---\n");
116-
ret = inject_rot_key();
117-
if (DEVICEKEY_SUCCESS != ret && DEVICEKEY_ALREADY_EXIST != ret) {
118-
printf("\n--- Error, injection of ROT key has failed with status %d ---\n", ret);
119-
return -1;
120-
}
121-
122-
if ( DEVICEKEY_ALREADY_EXIST == ret ) {
123-
printf("\n--- ROT Key already exists in the persistent memory. ---\n", ret);
124-
} else {
125-
printf("\n--- ROT Key injected and stored in persistent memory. ---\n", ret);
126-
}
127-
128-
#endif
129-
130-
printf("\n--- Using the following salt for key derivation: %s ---\n", salt1);
131-
132-
//16 byte key derivation.
133-
printf("--- First call to derive key, requesting derived key of 16 byte ---\n");
134-
ret = devkey.generate_derived_key(salt1, sizeof(salt1), derive_key1, DEVICE_KEY_16BYTE);
135-
if (DEVICEKEY_SUCCESS != ret) {
136-
printf("\n--- Error, derive key failed with error code %d ---\n", ret);
137-
return -1;
138-
}
139-
140-
printf("--- Derived key1 is: \n");
141-
print_buffer(derive_key1, DEVICE_KEY_16BYTE);
142-
printf("\n");
143-
144-
//16 byte key derivation with the same salt should result with the same derived key.
145-
printf("\n--- Second call to derive key with the same salt. ---\n");
146-
ret = devkey.generate_derived_key(salt1, sizeof(salt1), derive_key2, DEVICE_KEY_16BYTE);
147-
if (DEVICEKEY_SUCCESS != ret) {
148-
printf("\n--- Error, derive key failed with error code %d ---\n", ret);
149-
return -1;
150-
}
151-
152-
printf("--- Derived key2 should be equal to key1 from the first call. key2 is: \n");
153-
print_buffer(derive_key2, DEVICE_KEY_16BYTE);
154-
printf("\n");
155-
156-
if (memcmp(derive_key1, derive_key2, DEVICE_KEY_16BYTE) != 0) {
157-
printf("--- Error, first key and second key do not match ---\n");
158-
return -1;
159-
} else {
160-
printf("--- Keys match ---\n");
161-
}
162-
163-
printf("\n--- Using the following salt for key derivation %s ---\n", salt2);
164-
165-
//16 byte key derivation with the different salt should result with new derived key.
166-
ret = devkey.generate_derived_key(salt2, sizeof(salt2), derive_key1, DEVICE_KEY_16BYTE);
167-
if (DEVICEKEY_SUCCESS != ret) {
168-
printf("\n--- Error, derive key failed with error code %d ---\n", ret);
169-
return -1;
170-
}
171-
172-
printf("--- Third call to derive key with the different salt should result with a new derived key1: \n");
173-
print_buffer(derive_key1, DEVICE_KEY_16BYTE);
174-
printf("\n");
175-
176-
if (memcmp(derive_key1, derive_key2, DEVICE_KEY_16BYTE) == 0) {
177-
printf("--- Error, first key and second key do not match ---\n");
178-
return -1;
179-
} else {
180-
printf("--- Keys not match ---\n");
181-
}
182-
183-
//32 byte key derivation.
184-
printf("\n--- 32 byte key derivation example. ---\n");
185-
ret = devkey.generate_derived_key(salt2, sizeof(salt2), derive_key2, DEVICE_KEY_32BYTE);
186-
if (DEVICEKEY_SUCCESS != ret) {
187-
printf("\n--- Error, derive key failed with error code %d ---\n", ret);
188-
return -1;
189-
}
190-
191-
printf("--- 32 byte derived key is: \n");
192-
print_buffer(derive_key2, DEVICE_KEY_32BYTE);
193-
printf("\n");
194-
195-
printf("\n--- Mbed OS DeviceKey example done. ---\n");
196-
197-
return 0;
198-
}
199-
```
200-
60+
[![View Example](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/tree/master/DeviceKey)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/DeviceKey/main.cpp)

0 commit comments

Comments
 (0)