Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
DeviceKey.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2018 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef MBED_DEVICEKEY_H
17 #define MBED_DEVICEKEY_H
18 
19 #include "stddef.h"
20 #include "stdint.h"
21 #include "platform/NonCopyable.h"
22 
23 #define DEVICEKEY_ENABLED 1
24 
25 // Whole class is not supported if entropy is not enabled
26 // Flash device is required as Device Key is currently depending on it
27 #if !DEVICE_FLASH || !defined(COMPONENT_FLASHIAP)
28 #undef DEVICEKEY_ENABLED
29 #define DEVICEKEY_ENABLED 0
30 #endif
31 
32 #if (DEVICEKEY_ENABLED) || defined(DOXYGEN_ONLY)
33 
34 namespace mbed {
35 /** \addtogroup drivers */
36 
37 #define DEVICE_KEY_16BYTE 16
38 #define DEVICE_KEY_32BYTE 32
39 
40 enum DeviceKeyStatus {
41  DEVICEKEY_SUCCESS = 0,
42  DEVICEKEY_INVALID_KEY_SIZE = -1,
43  DEVICEKEY_INVALID_KEY_TYPE = -2,
44  DEVICEKEY_SAVE_FAILED = -3,
45  DEVICEKEY_ALREADY_EXIST = -4,
46  DEVICEKEY_NOT_FOUND = -5,
47  DEVICEKEY_READ_FAILED = -6,
48  DEVICEKEY_KVSTORE_UNPREDICTED_ERROR = -7,
49  DEVICEKEY_ERR_CMAC_GENERIC_FAILURE = -8,
50  DEVICEKEY_BUFFER_TOO_SMALL = -9,
51  DEVICEKEY_NO_KEY_INJECTED = -10,
52  DEVICEKEY_INVALID_PARAM = -11,
53  DEVICEKEY_GENERATE_RANDOM_ERROR = -12,
54 };
55 
56 /** Use this singleton if you need to derive a new key from the device root of trust.
57  *
58  * @note Synchronization level: Thread safe
59  * @ingroup drivers
60  */
61 
62 class DeviceKey : private mbed::NonCopyable<DeviceKey> {
63 public:
64 
65  /**
66  * @brief As a singleton, return the single instance of the class.
67  * Reason for this class being a singleton is the following:
68  * - Ease of use for users of this class not having to coordinate instantiations.
69  * - Lazy instantiation of internal data (which we can't achieve with simple static classes).
70  *
71  * @returns Singleton instance reference.
72  */
73  static DeviceKey &get_instance()
74  {
75  // Use this implementation of singleton (Meyer's) rather than the one that allocates
76  // the instance on the heap, as it ensures destruction at program end (preventing warnings
77  // from memory checking tools, such as valgrind).
78  static DeviceKey instance;
79  return instance;
80  }
81 
82  ~DeviceKey();
83 
84  /** Derive a new key based on the salt string.
85  * @param isalt Input buffer used to create the new key. Same input always generates the same key
86  * @param isalt_size Size of the data in salt buffer.
87  * @param output Buffer to receive the derived key. Size must be 16 bytes or 32 bytes
88  * according to the ikey_type parameter
89  * @param ikey_type Type of the required key. Must be 16 bytes or 32 bytes.
90  * @return 0 on success, negative error code on failure
91  */
92  int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type);
93 
94  /** Set a device key into the KVStore. If entropy support is missing, call this method
95  * before calling device_key_derived_key. This method should be called only once!
96  * @param value Input buffer contain the key.
97  * @param isize Size of the supplied key. Must be 16 bytes or 32 bytes.
98  * @return 0 on success, negative error code on failure
99  */
100  int device_inject_root_of_trust(uint32_t *value, size_t isize);
101 
102 private:
103  // Private constructor, as class is a singleton
104  DeviceKey();
105 
106  /** Read a device key from the KVStore
107  * @param output Buffer for the returned key.
108  * @param size Input: The size of the output buffer.
109  * Output: The actual size of the written data
110  * @return 0 on success, negative error code on failure
111  */
112  int read_key_from_kvstore(uint32_t *output, size_t &size);
113 
114  /** Set a device key into the KVStore
115  * @param input Input buffer contain the key.
116  * @param isize The size of the input buffer.
117  * @return 0 on success, negative error code on failure
118  */
119  int write_key_to_kvstore(uint32_t *input, size_t isize);
120 
121  /** Get a derived key base on a salt string. The methods implements Section 5.1
122  * in NIST SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions
123  * @param ikey_buff Input buffer holding the ROT key
124  * @param ikey_size Size of the input key. Must be 16 bytes or 32 bytes.
125  * @param isalt Input buffer contain some string.
126  * @param isalt_size Size of the supplied input string.
127  * @param output Buffer for the derived key result.
128  * @param ikey_type The requested key size. Must be 16 bytes or 32 bytes.
129  * @return 0 on success, negative error code on failure
130  */
131  int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size,
132  unsigned char *output, uint32_t ikey_type);
133 
134  /** Generate a random ROT key by using entropy
135  * @param output Output buffer for the generated key.
136  * @param size Input: The size of the buffer. If size is less
137  * than 16 bytes, the method generates an
138  * error. 16-31 bytes creates a 16-byte key.
139  * 32 or higher generates a 32-byte key
140  * Output: The actual written size to the buffer
141  * @return 0 on success, negative error code on failure
142  */
143  int generate_key_by_random(uint32_t *output, size_t size);
144 
145 };
146 /** @}*/
147 
148 }
149 
150 #endif
151 #endif
152 
mbed::DeviceKey::get_instance
static DeviceKey & get_instance()
As a singleton, return the single instance of the class.
Definition: DeviceKey.h:73
mbed::DeviceKey::device_inject_root_of_trust
int device_inject_root_of_trust(uint32_t *value, size_t isize)
Set a device key into the KVStore.
mbed::DeviceKey::generate_derived_key
int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type)
Derive a new key based on the salt string.
mbed::NonCopyable
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:168
mbed::DeviceKey
Use this singleton if you need to derive a new key from the device root of trust. ...
Definition: DeviceKey.h:62
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.