Merge branch 'deepikabhavnani-device_key' into rollup-aus_writathon

Author: Cruz Monrreal II

features/device_key/source/DeviceKey.h

@@ -56,7 +56,7 @@ class DeviceKey : private mbed::NonCopyable<DeviceKey> {
     /**
      * @brief As a singleton, return the single instance of the class.
      *        Reason for this class being a singleton is the following:
-     *        - Ease the use for users of this class not having to coordinate instantiations.
+     *        - 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.
@@ -65,27 +65,27 @@ class DeviceKey : private mbed::NonCopyable<DeviceKey> {
     {
         // 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).
+        // from memory checking tools, such as valgrind).
         static DeviceKey instance;
         return instance;
     }
 
     ~DeviceKey();
 
-    /** Derive a new key based on the salt string. key type can be with values 16 bytes and 32 bytes
-     * @param isalt input buffer used to create the new key. Same input will generate always 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
+    /** 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. Type must be 16 bytes or 32 bytes.
+     * @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 NVStore. In case TRNG support is missing, Call this method
+    /** Set a device key into the NVStore. If TRNG 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.
+     * @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);
@@ -95,40 +95,40 @@ class DeviceKey : private mbed::NonCopyable<DeviceKey> {
     DeviceKey();
 
     /** Read a device key from the NVStore
-     * @param output buffer for the returned key.
-     * @param size input: the size of the output buffer.
-     *             output: the actual size of the written data
+     * @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_nvstore(uint32_t *output, size_t& size);
 
     /** Set a device key into the NVStore
-     * @param input input buffer contain the key.
-     * @param isize the size of the input buffer.
+     * @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_nvstore(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.
+    /** 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);
 
     /** Generate a random ROT key by using TRNG
-     * @param output output buffer for the generated key.
-     * @param size input: the size of the buffer. if size is less
-     *                    then 16 bytes the method will generate an
-     *                    error. 16-31 bytes will create a 16 byte key.
-     *                    32 or higher will generate a 32 bytes key
-     *             output: the actual written size to the buffer
+     * @param output Output buffer for the generated key.
+     * @param size Input: The size of the buffer. If size is less
+     *                    than 16 bytes, the method generates an
+     *                    error. 16-31 bytes creates a 16-byte key.
+     *                    32 or higher generates a 32-byte key
+     *             Output: The actual written size to the buffer
      * @return 0 on success, negative error code on failure
      */
     int generate_key_by_trng(uint32_t *output, size_t size);