Diff: OneWire_Masters/ISha256MacCoprocessor.hpp

Revision:

49:36954b62f503

Parent:

48:6f9208ae280e

--- a/OneWire_Masters/ISha256MacCoprocessor.hpp	Thu Apr 07 11:26:20 2016 -0500
+++ b/OneWire_Masters/ISha256MacCoprocessor.hpp	Fri Apr 08 16:11:16 2016 -0500
@@ -6,7 +6,7 @@
 
 #include "array.hpp"
 
-/// Interface for SHA-256 coprocessors compatible with the DS28E15/22/25 family.
+/// Interface for SHA-256 coprocessors compatible with the DS28E15/22/25 family and similar.
 class ISha256MacCoprocessor
 {
 public:
@@ -16,12 +16,25 @@
     OperationFailure
   };
 
+  /// Holds the contents of a device memory page.
   typedef array<std::uint8_t, 32> DevicePage;
+  
+  /// Holds the contents of a device scratchpad.
   typedef array<std::uint8_t, 32> DeviceScratchpad;
+  
+  /// Holds the contents of a device secret.
   typedef array<std::uint8_t, 32> Secret;
+  
+  /// Container for a SHA-256 MAC.
   typedef array<std::uint8_t, 32> Mac;
+  
+  /// Additional data fields for Compute Write MAC operation.
   typedef array<std::uint8_t, 20> WriteMacData;
+  
+  /// Additional data fields for the Compute Auth. MAC operation.
   typedef array<std::uint8_t, 12> AuthMacData;
+  
+  /// Additional data field for the Compute Slave Secret operation.
   typedef array<std::uint8_t, 12> SlaveSecretData;
   
   /// Set Master Secret in coprocessor.
@@ -32,12 +45,12 @@
   /// @note Uses the previously set Master Secret in computation.
   /// @param[in] devicePage Page data stored on device.
   /// @param[in] deviceScratchpad Scratchpad data stored on device.
-  /// @param[in] slaveSecretData Variable data field used in calculation.
+  /// @param[in] slaveSecretData Additional data fields as specified by device.
   virtual CmdResult computeSlaveSecret(const DevicePage & devicePage, const DeviceScratchpad & deviceScratchpad, const SlaveSecretData & slaveSecretData) = 0;
   
   /// Compute Write MAC
   /// @note Uses the previously computed Slave Secret in computation.
-  /// @param[in] writeMacData Variable data fields used in calculation.
+  /// @param[in] writeMacData Additional data fields as specified by device.
   /// @param[out] mac The computed MAC.
   virtual CmdResult computeWriteMac(const WriteMacData & writeMacData, Mac & mac) const = 0;
   
@@ -45,7 +58,7 @@
   /// @note Uses the previously computed Slave Secret in computation.
   /// @param[in] devicePage Page data stored on device.
   /// @param[in] challege Random challenge for device.
-  /// @param[in] authMacData Variable data fields used in calculation.
+  /// @param[in] authMacData Additional data fields as specified by device.
   /// @param[out] mac The computed MAC.
   virtual CmdResult computeAuthMac(const DevicePage & devicePage, const DeviceScratchpad & challenge, const AuthMacData & authMacData, Mac & mac) const = 0;
 };