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 device-security Device Key
36  * \ingroup mbed-os-public
37  * @{
38  */
39 
40 
41 #define DEVICE_KEY_16BYTE 16
42 #define DEVICE_KEY_32BYTE 32
43 
44 enum DeviceKeyStatus {
45  DEVICEKEY_SUCCESS = 0,
46  DEVICEKEY_INVALID_KEY_SIZE = -1,
47  DEVICEKEY_INVALID_KEY_TYPE = -2,
48  DEVICEKEY_SAVE_FAILED = -3,
49  DEVICEKEY_ALREADY_EXIST = -4,
50  DEVICEKEY_NOT_FOUND = -5,
51  DEVICEKEY_READ_FAILED = -6,
52  DEVICEKEY_KVSTORE_UNPREDICTED_ERROR = -7,
53  DEVICEKEY_ERR_CMAC_GENERIC_FAILURE = -8,
54  DEVICEKEY_BUFFER_TOO_SMALL = -9,
55  DEVICEKEY_NO_KEY_INJECTED = -10,
56  DEVICEKEY_INVALID_PARAM = -11,
57  DEVICEKEY_GENERATE_RANDOM_ERROR = -12,
58 };
59 
60 /** Use this singleton if you need to derive a new key from the device root of trust.
61  *
62  * @note Synchronization level: Thread safe
63  * @ingroup device-key
64  */
65 /**
66  * \defgroup device-security_DeviceKey DeviceKey class
67  * \addtogroup device-security
68  * @{
69  */
70 class DeviceKey : private mbed::NonCopyable<DeviceKey> {
71 public:
72 
73  /**
74  * @brief As a singleton, return the single instance of the class.
75  * Reason for this class being a singleton is the following:
76  * - Ease of use for users of this class not having to coordinate instantiations.
77  * - Lazy instantiation of internal data (which we can't achieve with simple static classes).
78  *
79  * @returns Singleton instance reference.
80  */
81  static DeviceKey &get_instance()
82  {
83  // Use this implementation of singleton (Meyer's) rather than the one that allocates
84  // the instance on the heap, as it ensures destruction at program end (preventing warnings
85  // from memory checking tools, such as valgrind).
86  static DeviceKey instance;
87  return instance;
88  }
89 
90  ~DeviceKey();
91 
92  /** Derive a new key based on the salt string.
93  * @param isalt Input buffer used to create the new key. Same input always generates the same key
94  * @param isalt_size Size of the data in salt buffer.
95  * @param output Buffer to receive the derived key. Size must be 16 bytes or 32 bytes
96  * according to the ikey_type parameter
97  * @param ikey_type Type of the required key. Must be 16 bytes or 32 bytes.
98  * @return 0 on success, negative error code on failure
99  */
100  int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type);
101 
102  /** Set a device key into the KVStore. If entropy support is missing, call this method
103  * before calling device_key_derived_key. This method should be called only once!
104  * @param value Input buffer contain the key.
105  * @param isize Size of the supplied key. Must be 16 bytes or 32 bytes.
106  * @return 0 on success, negative error code on failure
107  */
108  int device_inject_root_of_trust(uint32_t *value, size_t isize);
109 
110 private:
111  // Private constructor, as class is a singleton
112  DeviceKey();
113 
114  /** Read a device key from the KVStore
115  * @param output Buffer for the returned key.
116  * @param size Input: The size of the output buffer.
117  * Output: The actual size of the written data
118  * @return 0 on success, negative error code on failure
119  */
120  int read_key_from_kvstore(uint32_t *output, size_t &size);
121 
122  /** Set a device key into the KVStore
123  * @param input Input buffer contain the key.
124  * @param isize The size of the input buffer.
125  * @return 0 on success, negative error code on failure
126  */
127  int write_key_to_kvstore(uint32_t *input, size_t isize);
128 
129  /** Get a derived key base on a salt string. The methods implements Section 5.1
130  * in NIST SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions
131  * @param ikey_buff Input buffer holding the ROT key
132  * @param ikey_size Size of the input key. Must be 16 bytes or 32 bytes.
133  * @param isalt Input buffer contain some string.
134  * @param isalt_size Size of the supplied input string.
135  * @param output Buffer for the derived key result.
136  * @param ikey_type The requested key size. Must be 16 bytes or 32 bytes.
137  * @return 0 on success, negative error code on failure
138  */
139  int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size,
140  unsigned char *output, uint32_t ikey_type);
141 
142  /** Generate a random ROT key by using entropy
143  * @param output Output buffer for the generated key.
144  * @param size Input: The size of the buffer. If size is less
145  * than 16 bytes, the method generates an
146  * error. 16-31 bytes creates a 16-byte key.
147  * 32 or higher generates a 32-byte key
148  * Output: The actual written size to the buffer
149  * @return 0 on success, negative error code on failure
150  */
151  int generate_key_by_random(uint32_t *output, size_t size);
152 
153 };
154 
155 /** @}*/
156 /** @}*/
157 
158 }
159 
160 #endif
161 #endif
162 
mbed::DeviceKey::get_instance
static DeviceKey & get_instance()
As a singleton, return the single instance of the class.
Definition: DeviceKey.h:81
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:169
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.