DeviceKey.h

/* mbed Microcontroller Library
 * Copyright (c) 2018 ARM Limited
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef MBED_DEVICEKEY_H
#define MBED_DEVICEKEY_H
 
#include "stddef.h"
#include "stdint.h"
#include "platform/NonCopyable.h"
 
#define DEVICEKEY_ENABLED 1
 
// Whole class is not supported if entropy is not enabled
// Flash device is required as Device Key is currently depending on it
#if !DEVICE_FLASH
#undef DEVICEKEY_ENABLED
#define DEVICEKEY_ENABLED 0
#endif
 
#if (DEVICEKEY_ENABLED) || defined(DOXYGEN_ONLY)
 
namespace mbed {
/** \addtogroup drivers-public-api
 * @{
 */
 
 
#define DEVICE_KEY_16BYTE 16
#define DEVICE_KEY_32BYTE 32
 
enum DeviceKeyStatus {
    DEVICEKEY_SUCCESS                     =  0,
    DEVICEKEY_INVALID_KEY_SIZE            = -1,
    DEVICEKEY_INVALID_KEY_TYPE            = -2,
    DEVICEKEY_SAVE_FAILED                 = -3,
    DEVICEKEY_ALREADY_EXIST               = -4,
    DEVICEKEY_NOT_FOUND                   = -5,
    DEVICEKEY_READ_FAILED                 = -6,
    DEVICEKEY_KVSTORE_UNPREDICTED_ERROR   = -7,
    DEVICEKEY_ERR_CMAC_GENERIC_FAILURE    = -8,
    DEVICEKEY_BUFFER_TOO_SMALL            = -9,
    DEVICEKEY_NO_KEY_INJECTED             = -10,
    DEVICEKEY_INVALID_PARAM               = -11,
    DEVICEKEY_GENERATE_RANDOM_ERROR       = -12,
};
 
/** Use this singleton if you need to derive a new key from the device root of trust.
 *
 * @note Synchronization level: Thread safe
 * @ingroup device-key
 */
/**
 */
class DeviceKey : private mbed::NonCopyable<DeviceKey> {
public:
 
    /**
     * @brief As a singleton, return the single instance of the class.
     *        Reason for this class being a singleton is the following:
     *        - Ease of use for users of this class not having to coordinate instantiations.
     *        - Lazy instantiation of internal data (which we can't achieve with simple static classes).
     *
     * @returns Singleton instance reference.
     */
    static DeviceKey &get_instance()
    {
        // Use this implementation of singleton (Meyer's) rather than the one that allocates
        // the instance on the heap, as it ensures destruction at program end (preventing warnings
        // from memory checking tools, such as valgrind).
        static DeviceKey instance;
        return instance;
    }
 
    ~DeviceKey();
 
    /** Derive a new key based on the salt string.
     * @param isalt Input buffer used to create the new key. Same input always generates the same key
     * @param isalt_size Size of the data in salt buffer.
     * @param output Buffer to receive the derived key. Size must be 16 bytes or 32 bytes
     *               according to the ikey_type parameter
     * @param ikey_type Type of the required key. Must be 16 bytes or 32 bytes.
     * @return 0 on success, negative error code on failure
     */
    int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type);
 
    /** Set a device key into the KVStore. If entropy support is missing, call this method
     *  before calling device_key_derived_key. This method should be called only once!
     * @param value Input buffer contain the key.
     * @param isize Size of the supplied key. Must be 16 bytes or 32 bytes.
     * @return 0 on success, negative error code on failure
     */
    int device_inject_root_of_trust(uint32_t *value, size_t isize);
    /** Generate Root of Trust.
     * Uses TRNG or various other entropy sources to generate random device key and
     * inject it into device's KVStore. Device Key can only be generated once.
     *
     * @param key_size Size of key in bytes to generate. Must be 16 bytes or 32 bytes. Default is 16 bytes.
     *
     * @return DEVICEKEY_SUCCESS, when device key successfully generated and injected.
     * @return DEVICEKEY_ALREADY_EXIST, if the key has already been written.
     * @return DEVICEKEY_GENERATE_RANDOM_ERROR if this device does not contain entropy sources and cannot generate a key.
     * @return DEVICEKEY_INVALID_KEY_SIZE if key_size is not 32 or 16 bytes.
     * @return error codes on other failures.
     */
    int generate_root_of_trust(size_t key_size = DEVICE_KEY_16BYTE);
 
private:
    // Private constructor, as class is a singleton
    DeviceKey();
 
    /** Read a device key from the KVStore
     * @param output Buffer for the returned key.
     * @param size Input: The size of the output buffer.
     *             Output: The actual size of the written data
     * @return 0 on success, negative error code on failure
     */
    int read_key_from_kvstore(uint32_t *output, size_t &size);
 
    /** Set a device key into the KVStore
     * @param input Input buffer contain the key.
     * @param isize The size of the input buffer.
     * @return 0 on success, negative error code on failure
     */
    int write_key_to_kvstore(uint32_t *input, size_t isize);
 
    /** Get a derived key base on a salt string. The methods implements Section 5.1
     *  in NIST SP 800-108, Recommendation for Key Derivation Using Pseudorandom Functions
     * @param ikey_buff Input buffer holding the ROT key
     * @param ikey_size Size of the input key. Must be 16 bytes or 32 bytes.
     * @param isalt Input buffer contain some string.
     * @param isalt_size Size of the supplied input string.
     * @param output Buffer for the derived key result.
     * @param ikey_type The requested key size. Must be 16 bytes or 32 bytes.
     * @return 0 on success, negative error code on failure
     */
    int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size,
                        unsigned char *output, uint32_t ikey_type);
 
};
 
/** @}*/
 
}
 
#endif
#endif