Skip to content

Commit 313fe56

Browse files
author
Amanda Butler
authored
Merge pull request #785 from deepikabhavnani/device_key
DeviceKey page update
2 parents 63a9bb2 + f7417ab commit 313fe56

File tree

1 file changed

+4
-146
lines changed

1 file changed

+4
-146
lines changed

‎docs/api/drivers/Devicekey.md

Lines changed: 4 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,15 @@ The root of trust is generated at the first use of DeviceKey if the true random
2323

2424
### Key derivation API
2525

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.
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 have any value - array, string and so on.
2727

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

3030
#### Root of Trust Injection API
3131

3232
`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).
3333

34-
#### Using DeviceKey
34+
#### Using DeviceKey
3535

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

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

4646
Run the DeviceKey functionality test with the `mbed` command as following:
4747

48-
```
48+
```
4949
mbed test -n features-device_key-tests-device_key-functionality
5050
```
5151

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

5656
### DeviceKey example
5757

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-
58+
[![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)