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 #if (NVSTORE_ENABLED) || defined(DOXYGEN_ONLY)
00024 
00025 namespace mbed {
00026 /** \addtogroup drivers */
00027 
00028 #define DEVICE_KEY_16BYTE 16
00029 #define DEVICE_KEY_32BYTE 32
00030 
00031 enum DeviceKeyStatus {
00032     DEVICEKEY_SUCCESS                     =  0,
00033     DEVICEKEY_INVALID_KEY_SIZE            = -1,
00034     DEVICEKEY_INVALID_KEY_TYPE            = -2,
00035     DEVICEKEY_SAVE_FAILED                 = -3,
00036     DEVICEKEY_ALREADY_EXIST               = -4,
00037     DEVICEKEY_NOT_FOUND                   = -5,
00038     DEVICEKEY_READ_FAILED                 = -6,
00039     DEVICEKEY_NVSTORE_UNPREDICTED_ERROR   = -7,
00040     DEVICEKEY_ERR_CMAC_GENERIC_FAILURE    = -8,
00041     DEVICEKEY_BUFFER_TOO_SMALL            = -9,
00042     DEVICEKEY_NO_KEY_INJECTED             = -10,
00043     DEVICEKEY_INVALID_PARAM               = -11,
00044     DEVICEKEY_TRNG_ERROR                  = -12,
00045 };
00046 
00047 /** Use this singleton if you need to derive a new key from the device root of trust.
00048  *
00049  * @note Synchronization level: Thread safe
00050  * @ingroup drivers
00051  */
00052 
00053 class DeviceKey : private mbed::NonCopyable<DeviceKey> {
00054 public:
00055 
00056     /**
00057      * @brief As a singleton, return the single instance of the class.
00058      *        Reason for this class being a singleton is the following:
00059      *        - Ease of use for users of this class not having to coordinate instantiations.
00060      *        - Lazy instantiation of internal data (which we can't achieve with simple static classes).
00061      *
00062      * @returns Singleton instance reference.
00063      */
00064     static DeviceKey& get_instance()
00065     {
00066         // Use this implementation of singleton (Meyer's) rather than the one that allocates
00067         // the instance on the heap, as it ensures destruction at program end (preventing warnings
00068         // from memory checking tools, such as valgrind).
00069         static DeviceKey instance;
00070         return instance;
00071     }
00072 
00073     ~DeviceKey();
00074 
00075     /** Derive a new key based on the salt string.
00076      * @param isalt Input buffer used to create the new key. Same input always generates the same key
00077      * @param isalt_size Size of the data in salt buffer.
00078      * @param output Buffer to receive the derived key. Size must be 16 bytes or 32 bytes
00079      *               according to the ikey_type parameter
00080      * @param ikey_type Type of the required key. Must be 16 bytes or 32 bytes.
00081      * @return 0 on success, negative error code on failure
00082      */
00083     int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type);
00084 
00085     /** Set a device key into the NVStore. If TRNG support is missing, call this method
00086      *  before calling device_key_derived_key. This method should be called only once!
00087      * @param value Input buffer contain the key.
00088      * @param isize Size of the supplied key. Must be 16 bytes or 32 bytes.
00089      * @return 0 on success, negative error code on failure
00090      */
00091     int device_inject_root_of_trust(uint32_t *value, size_t isize);
00092 
00093 private:
00094     // Private constructor, as class is a singleton
00095     DeviceKey();
00096 
00097     /** Read a device key from the NVStore
00098      * @param output Buffer for the returned key.
00099      * @param size Input: The size of the output buffer.
00100      *             Output: The actual size of the written data
00101      * @return 0 on success, negative error code on failure
00102      */
00103     int read_key_from_nvstore(uint32_t *output, size_t& size);
00104 
00105     /** Set a device key into the NVStore
00106      * @param input Input buffer contain the key.
00107      * @param isize The size of the input buffer.
00108      * @return 0 on success, negative error code on failure
00109      */
00110     int write_key_to_nvstore(uint32_t *input, size_t isize);
00111 
00112     /** Get a derived key base on a salt string. The methods implements Section 5.1 
00113      *  in NIST SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions
00114      * @param ikey_buff Input buffer holding the ROT key
00115      * @param ikey_size Size of the input key. Must be 16 bytes or 32 bytes.
00116      * @param isalt Input buffer contain some string.
00117      * @param isalt_size Size of the supplied input string.
00118      * @param output Buffer for the derived key result.
00119      * @param ikey_type The requested key size. Must be 16 bytes or 32 bytes.
00120      * @return 0 on success, negative error code on failure
00121      */
00122     int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size,
00123                         unsigned char *output, uint32_t ikey_type);
00124 
00125     /** Generate a random ROT key by using TRNG
00126      * @param output Output buffer for the generated key.
00127      * @param size Input: The size of the buffer. If size is less
00128      *                    than 16 bytes, the method generates an
00129      *                    error. 16-31 bytes creates a 16-byte key.
00130      *                    32 or higher generates a 32-byte key
00131      *             Output: The actual written size to the buffer
00132      * @return 0 on success, negative error code on failure
00133      */
00134     int generate_key_by_trng(uint32_t *output, size_t size);
00135 
00136 };
00137 /** @}*/
00138 
00139 }
00140 
00141 #endif //NVSTORE_ENABLED
00142 #endif