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