DeviceKey.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_DEVICEKEY_H
00017 #define MBED_DEVICEKEY_H
00018 
00019 #include "stddef.h"
00020 #include "stdint.h"
00021 #include "platform/NonCopyable.h"
00022 
00023 #define DEVICEKEY_ENABLED 1
00024 
00025 // Whole class is not supported if entropy is not enabled
00026 // Flash device is required as Device Key is currently depending on it
00027 #if !DEVICE_FLASH || !defined(COMPONENT_FLASHIAP)
00028 #undef DEVICEKEY_ENABLED
00029 #define DEVICEKEY_ENABLED 0
00030 #endif
00031 
00032 #if (DEVICEKEY_ENABLED) || defined(DOXYGEN_ONLY)
00033 
00034 namespace mbed {
00035 /** \addtogroup device-security Device Key
00036  * \ingroup mbed-os-public
00037  * @{
00038  */
00039 
00040 
00041 #define DEVICE_KEY_16BYTE 16
00042 #define DEVICE_KEY_32BYTE 32
00043 
00044 enum DeviceKeyStatus {
00045     DEVICEKEY_SUCCESS                     =  0,
00046     DEVICEKEY_INVALID_KEY_SIZE            = -1,
00047     DEVICEKEY_INVALID_KEY_TYPE            = -2,
00048     DEVICEKEY_SAVE_FAILED                 = -3,
00049     DEVICEKEY_ALREADY_EXIST               = -4,
00050     DEVICEKEY_NOT_FOUND                   = -5,
00051     DEVICEKEY_READ_FAILED                 = -6,
00052     DEVICEKEY_KVSTORE_UNPREDICTED_ERROR   = -7,
00053     DEVICEKEY_ERR_CMAC_GENERIC_FAILURE    = -8,
00054     DEVICEKEY_BUFFER_TOO_SMALL            = -9,
00055     DEVICEKEY_NO_KEY_INJECTED             = -10,
00056     DEVICEKEY_INVALID_PARAM               = -11,
00057     DEVICEKEY_GENERATE_RANDOM_ERROR       = -12,
00058 };
00059 
00060 /** Use this singleton if you need to derive a new key from the device root of trust.
00061  *
00062  * @note Synchronization level: Thread safe
00063  * @ingroup device-key
00064  */
00065 /**
00066  * \defgroup device-security_DeviceKey DeviceKey class
00067  * \addtogroup device-security
00068  * @{
00069  */
00070 class DeviceKey : private mbed::NonCopyable<DeviceKey> {
00071 public:
00072 
00073     /**
00074      * @brief As a singleton, return the single instance of the class.
00075      *        Reason for this class being a singleton is the following:
00076      *        - Ease of use for users of this class not having to coordinate instantiations.
00077      *        - Lazy instantiation of internal data (which we can't achieve with simple static classes).
00078      *
00079      * @returns Singleton instance reference.
00080      */
00081     static DeviceKey &get_instance()
00082     {
00083         // Use this implementation of singleton (Meyer's) rather than the one that allocates
00084         // the instance on the heap, as it ensures destruction at program end (preventing warnings
00085         // from memory checking tools, such as valgrind).
00086         static DeviceKey instance;
00087         return instance;
00088     }
00089 
00090     ~DeviceKey();
00091 
00092     /** Derive a new key based on the salt string.
00093      * @param isalt Input buffer used to create the new key. Same input always generates the same key
00094      * @param isalt_size Size of the data in salt buffer.
00095      * @param output Buffer to receive the derived key. Size must be 16 bytes or 32 bytes
00096      *               according to the ikey_type parameter
00097      * @param ikey_type Type of the required key. Must be 16 bytes or 32 bytes.
00098      * @return 0 on success, negative error code on failure
00099      */
00100     int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type);
00101 
00102     /** Set a device key into the KVStore. If entropy support is missing, call this method
00103      *  before calling device_key_derived_key. This method should be called only once!
00104      * @param value Input buffer contain the key.
00105      * @param isize Size of the supplied key. Must be 16 bytes or 32 bytes.
00106      * @return 0 on success, negative error code on failure
00107      */
00108     int device_inject_root_of_trust(uint32_t *value, size_t isize);
00109 
00110 private:
00111     // Private constructor, as class is a singleton
00112     DeviceKey();
00113 
00114     /** Read a device key from the KVStore
00115      * @param output Buffer for the returned key.
00116      * @param size Input: The size of the output buffer.
00117      *             Output: The actual size of the written data
00118      * @return 0 on success, negative error code on failure
00119      */
00120     int read_key_from_kvstore(uint32_t *output, size_t &size);
00121 
00122     /** Set a device key into the KVStore
00123      * @param input Input buffer contain the key.
00124      * @param isize The size of the input buffer.
00125      * @return 0 on success, negative error code on failure
00126      */
00127     int write_key_to_kvstore(uint32_t *input, size_t isize);
00128 
00129     /** Get a derived key base on a salt string. The methods implements Section 5.1
00130      *  in NIST SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions
00131      * @param ikey_buff Input buffer holding the ROT key
00132      * @param ikey_size Size of the input key. Must be 16 bytes or 32 bytes.
00133      * @param isalt Input buffer contain some string.
00134      * @param isalt_size Size of the supplied input string.
00135      * @param output Buffer for the derived key result.
00136      * @param ikey_type The requested key size. Must be 16 bytes or 32 bytes.
00137      * @return 0 on success, negative error code on failure
00138      */
00139     int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size,
00140                         unsigned char *output, uint32_t ikey_type);
00141 
00142     /** Generate a random ROT key by using entropy
00143      * @param output Output buffer for the generated key.
00144      * @param size Input: The size of the buffer. If size is less
00145      *                    than 16 bytes, the method generates an
00146      *                    error. 16-31 bytes creates a 16-byte key.
00147      *                    32 or higher generates a 32-byte key
00148      *             Output: The actual written size to the buffer
00149      * @return 0 on success, negative error code on failure
00150      */
00151     int generate_key_by_random(uint32_t *output, size_t size);
00152 
00153 };
00154 
00155 /** @}*/
00156 /** @}*/
00157 
00158 }
00159 
00160 #endif
00161 #endif
00162