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 the 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. key type can be with values 16 bytes and 32 bytes
00076      * @param isalt input buffer used to create the new key. Same input will generate always 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. Type 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. In case 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
00113      * Section 5.1 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      *                    then 16 bytes the method will generate an
00129      *                    error. 16-31 bytes will create a 16 byte key.
00130      *                    32 or higher will generate a 32 bytes 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