File content as of revision 73:2cecc1372acc:

//------------Copyright (C) 2013 Maxim Integrated Products --------------
//
// Permission is hereby granted, free of charge, to any person obtaining a
// copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
// IN NO EVENT SHALL MAXIM INTEGRATED PRODCUTS BE LIABLE FOR ANY CLAIM, DAMAGES
// OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
// OTHER DEALINGS IN THE SOFTWARE.
//
// Except as contained in this notice, the name of Maxim Integrated Products
// shall not be used except as stated in the Maxim Integrated Products
// Branding Policy.
// ---------------------------------------------------------------------------

#ifndef OneWire_Authenticators_DS28E15_22_25
#define OneWire_Authenticators_DS28E15_22_25

#include "array.h"
#include "Authenticators/ISha256MacCoproc.h"
#include "OneWireSlave.h"

namespace OneWire
{
  namespace Masters { class OneWireMaster; }

  namespace Authenticators
  {
    /// Interface to the DS28E15/22/25 series of authenticators
    /// including low power variants.
    class DS28E15_22_25 : public OneWireSlave
    {
    public:
      /// Family code for each device.
      enum FamilyCode
      {
        DS28E25_FAMILY = 0x47,
        DS28E22_FAMILY = 0x48,
        DS28E15_FAMILY = 0x17,
        UNKNOWN_FAMILY = 0
      };

      /// Number for memory pages for each device.
      enum MemoryPages
      {
        DS28E25_PAGES = 16,
        DS28E22_PAGES = 8,
        DS28E15_PAGES = 2,
        UNKNOWN_PAGES = 0
      };
      
      /// Number of protection blocks for each device.
      enum ProtectionBlocks
      {
        DS28E25_BLOCKS = 8,
        DS28E22_BLOCKS = 4,
        DS28E15_BLOCKS = 4,
        UNKNOWN_BLOCKS = 0
      };
      
      /// Holds the contents of a device memory segment.
      typedef array<uint8_t, 4> Segment;
      
      /// Holds the contents of a device memory page.
      class Page
      {
      public:
        /// Length of the buffer in bytes.
        static const size_t length = 32;
        
      private:
        array<uint8_t, length> m_data;
        
      public:
        /// Built-in array representation.
        typedef array<uint8_t, length>::Buffer Buffer;
        
        Page() { }
        Page(const Page & page) : m_data(page.m_data) { }
        Page(const Buffer & dataBytes) : m_data(dataBytes) { }
        
        const Page & operator=(const Page & rhs)
        {
          this->m_data = rhs.m_data;
          return rhs;
        }
        
        bool operator==(const Page & rhs) const
        {
          return (this->m_data == rhs.m_data);
        }
        
        bool operator!=(const Page & rhs) const
        {
          return !operator==(rhs);
        }
        
        /// Conversion to array reference.
        operator Buffer &()
        {
          return m_data;
        }
        
        /// Conversion to const array reference.
        operator const Buffer &() const
        {
          return m_data;
        }
        
        /// Creates a segment representation from a subsection of the page data.
        /// @param segmentNum Segment number within page to copy from.
        /// @returns The copied segment data.
        Segment toSegment(unsigned int segmentNum) const;
        
        /// Copies segment data to the page.
        /// @param segmentNum Segment number within the page to copy to.
        /// @param[in] segment Segment to copy from.
        void fromSegment(unsigned int segmentNum, const Segment & segment);
      };
      
      /// Holds the contents of the device scratchpad.
      typedef array<uint8_t, 32> Scratchpad;
      
      /// Container for a SHA-256 MAC.
      typedef array<uint8_t, 32> Mac;
      
      /// Container for a manufacturer ID.
      typedef array<uint8_t, 2> ManId;
      
      /// Container for the device personality.
      union Personality
      {
        array<uint8_t, 4>::Buffer bytes;
        struct
        {
          uint8_t PB1;
          uint8_t PB2;
          ManId::Buffer manIdBytes;
          
          bool secretLocked() const { return (PB2 & 0x01); }
        } fields;
      };
      
      /// Represents the status of a memory protection block.
      class BlockProtection
      {
      private:
        static const uint8_t readProtectionMask = 0x80, writeProtectionMask = 0x40, eepromEmulationMask = 0x20, authProtectionMask = 0x10, blockNumMask = 0x0F;
        uint8_t m_status;
        
      public:
        BlockProtection() : m_status(0x00) { }
        BlockProtection(bool readProtection, bool writeProtection, bool eepromEmulation, bool authProtection, uint8_t blockNum);
      
        /// Get the byte representation used by the device.
        uint8_t statusByte() const { return m_status; }
        /// Set the byte representation used by the device.
        void setStatusByte(uint8_t status) { m_status = status; }
        
        /// Get the Block Number which is indexed from zero.
        uint8_t blockNum() const { return (m_status & blockNumMask); }
        /// Set the Block Number which is indexed from zero.
        void setBlockNum(uint8_t blockNum);
      
        /// Get the Read Protection status.
        /// @returns True if Read Protection is enabled.
        bool readProtection() const { return ((m_status & readProtectionMask) == readProtectionMask); }
        /// Set the Read Protection status.
        void setReadProtection(bool readProtection);
        
        /// Get the Write Protection status.
        /// @returns True if Write Protection is enabled.
        bool writeProtection() const { return ((m_status & writeProtectionMask) == writeProtectionMask); }
        /// Set the Write Protection status.
        void setWriteProtection(bool writeProtection);
        
        /// Get the EEPROM Emulation Mode status.
        /// @returns True if EEPROM Emulation Mode is enabled.
        bool eepromEmulation() const { return ((m_status & eepromEmulationMask) == eepromEmulationMask); }
        /// Set the EEPROM Emulation Mode status.
        void setEepromEmulation(bool eepromEmulation);
        
        /// Get the Authentication Protection status.
        /// @returns True if Authentication Protection is enabled.
        bool authProtection() const { return ((m_status & authProtectionMask) == authProtectionMask); }
        /// Set the Authentication Protection status.
        void setAuthProtection(bool authProtection);
        
        /// Check if no protection options are enabled.
        /// @returns True if no protection options are enabled.
        bool noProtection() const;
        
        bool operator==(const BlockProtection & rhs) const { return (this->m_status == rhs.m_status); }
        bool operator!=(const BlockProtection & rhs) const { return !operator==(rhs); }
      };
      
      /// Compute the MAC for an Authenticated Write to a memory segment.
      /// @param MacCoproc Coprocessor with Slave Secret to use for the computation.
      /// @param pageNum Page number for write operation.
      /// @param segmentNum Segment number within page for write operation.
      /// @param[in] newData New data to write to the segment.
      /// @param[in] oldData Existing data contained in the segment.
      /// @param[in] romId 1-Wire ROM ID of the device.
      /// @param[in] manId Manufacturer ID of the device.
      /// @param[out] mac The computed MAC.
      /// @returns The result code indicated by the coprocessor.
      static ISha256MacCoproc::CmdResult computeSegmentWriteMac(const ISha256MacCoproc & MacCoproc,
                                                                unsigned int pageNum,
                                                                unsigned int segmentNum,
                                                                const Segment & newData,
                                                                const Segment & oldData,
                                                                const RomId & romId,
                                                                const ManId & manId,
                                                                Mac & mac);
                                                                       
      /// Compute the MAC for an Authenticated Write to a memory protection block.
      /// @param MacCoproc Coprocessor with Slave Secret to use for the operation.
      /// @param[in] newProtection New protection status to write.
      /// @param[in] oldProtection Existing protection status in device.
      /// @param[in] romId 1-Wire ROM ID of the device.
      /// @param[in] manId Manufacturer ID of the device.
      /// @param[out] mac The computed MAC.
      /// @returns The result code indicated by the coprocessor.
      static ISha256MacCoproc::CmdResult computeProtectionWriteMac(const ISha256MacCoproc & MacCoproc,
                                                                   const BlockProtection & newProtection,
                                                                   const BlockProtection & oldProtection,
                                                                   const RomId & romId,
                                                                   const ManId & manId,
                                                                   Mac & mac);
      
      /// Compute the next secret from the existing secret.
      /// @param MacCoproc Coprocessor with Master Secret to use for the operation.
      ///        Slave Secret will be updated with the computation result.
      /// @param[in] bindingPage Binding data from a device memory page.
      /// @param bindingPageNum Number of the page where the binding data is from.
      /// @param[in] partialSecret Partial secret data from the device scratchpad.
      /// @param[in] romId 1-Wire ROM ID of the device.
      /// @param[in] manId Manufacturer ID of the device.
      /// @returns The result code indicated by the coprocessor.
      static ISha256MacCoproc::CmdResult computeNextSecret(ISha256MacCoproc & MacCoproc,
                                                           const Page & bindingPage,
                                                           unsigned int bindingPageNum,
                                                           const Scratchpad & partialSecret,
                                                           const RomId & romId,
                                                           const ManId & manId);
      
      /// Compute a Page MAC for authentication.
      /// @param MacCoproc Coprocessor with Slave Secret to use for the operation.
      /// @param[in] pageData Data from a device memory page.
      /// @param pageNum Number of the page to use data from.
      /// @param[in] challenge Random challenge to prevent replay attacks.
      /// @param[in] romId 1-Wire ROM ID of the device.
      /// @param[in] manId Manufacturer ID of the device.
      /// @param[out] mac The computed MAC.
      static ISha256MacCoproc::CmdResult computeAuthMac(const ISha256MacCoproc & MacCoproc,
                                                        const Page & pageData,
                                                        unsigned int pageNum,
                                                        const Scratchpad & challenge,
                                                        const RomId & romId,
                                                        const ManId & manId,
                                                        Mac & mac);
                                                             
      /// Compute a Page MAC for authentication using anonymous mode.
      /// @param MacCoproc Coprocessor with Slave Secret to use for the operation.
      /// @param[in] pageData Data from a device memory page.
      /// @param pageNum Number of the page to use data from.
      /// @param[in] challenge Random challenge to prevent replay attacks.
      /// @param[in] manId Manufacturer ID of the device.
      /// @param[out] mac The computed MAC.
      static ISha256MacCoproc::CmdResult computeAuthMacAnon(const ISha256MacCoproc & MacCoproc,
                                                            const Page & pageData,
                                                            unsigned int pageNum,
                                                            const Scratchpad & challenge,
                                                            const ManId & manId,
                                                            Mac & mac);
      
      /// Number of segments per page.
      static const unsigned int segmentsPerPage = (Page::length / Segment::length);
      
      /// Manufacturer ID
      ManId manId;
      
      /// Enable low voltage timing
      bool lowVoltage;
      
      /// @param OW_master 1-Wire Master to use for communication with DS28E15/22/25.
      /// @param lowVoltage Enable low voltage timing.
      DS28E15_22_25(Masters::OneWireMaster & OW_master, bool lowVoltage = false);
      
      // Const member functions should not affect the state of the memory, block protection, or secret on the DS28Exx.
      // Scratchpad on the DS28Exx is considered mutable.

      /// Get the number of memory pages from the ROM ID of this device.
      MemoryPages memoryPages();
      
      /// Get the number of protection blocks from the ROM ID of this device.
      ProtectionBlocks protectionBlocks();
      
      /// Perform Load and Lock Secret command on the device.
      /// @note The secret should already be stored in the scratchpad on the device.
      /// @param lock Prevent further changes to the secret on the device after loading.
      CmdResult loadSecret(bool lock);
      
      /// Perform Write Scratchpad operation on the device.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param[in] data Data to write to the scratchpad.
      CmdResult writeScratchpad(const Scratchpad & data) const;
      
      /// Perform a Read Scratchpad operation on the device.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param[out] data Buffer to read data from the scratchpad into.
      CmdResult readScratchpad(Scratchpad & data) const;
      
      /// Read memory segment using the Read Memory command on the device.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param pageNum Page number for read operation.
      /// @param segmentNum Segment number within page for read operation.
      /// @param[out] data Buffer to read data from the segment into.
      /// @param continuing True if continuing a previous Read Memory command.
      ///                   False to begin a new command.
      CmdResult readSegment(unsigned int pageNum, unsigned int segmentNum, Segment & data, bool continuing = false) const;
      
      /// Write memory segment using the Write Memory command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param pageNum Page number for write operation.
      /// @param segmentNum Segment number within page for write operation.
      /// @param[in] data Data to write to the memory segment.
      /// @param continuing True to continue writing with the next sequential segment.
      ///                   False to begin a new command.
      CmdResult writeSegment(unsigned int pageNum, unsigned int segmentNum, const Segment & data, bool continuing = false);
      
      /// Read memory page using the Read Memory command on the device.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param pageNum Page number for write operation.
      /// @param[out] rdbuf Buffer to read data from the page into.
      /// @param continuing True if continuing a previous Read Memory command.
      ///                   False to begin a new command.
      CmdResult readPage(unsigned int pageNum, Page & rdbuf, bool continuing = false) const;
      
      /// Perform a Compute and Lock Secret command on the device.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param pageNum Page number to use as the binding data.
      /// @param lock Prevent further changes to the secret on the device after computing.
      CmdResult computeSecret(unsigned int pageNum, bool lock);
      
      /// Perform a Compute Page MAC command on the device.
      /// Read back the MAC and verify the CRC16.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param pageNum Page number to use for the computation.
      /// @param anon True to compute in anonymous mode where ROM ID is not used.
      /// @param[out] mac The device computed MAC.
      CmdResult computeReadPageMac(unsigned int pageNum, bool anon, Mac & mac) const;
      
      /// Read the status of a memory protection block using the Read Status command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param blockNum Block number to to read status of.
      /// @param[out] protection Receives protection status read from device.
      CmdResult readBlockProtection(unsigned int blockNum, BlockProtection & protection);
      
      /// @{
      /// Read the status of all memory protection blocks using the Read Status command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param[out] protection Receives protection statuses read from device.
      CmdResult readAllBlockProtection(BlockProtection (&protection)[DS28E15_BLOCKS]) const;
      CmdResult readAllBlockProtection(BlockProtection (&protection)[DS28E25_BLOCKS]) const;
      /// @}
      
      /// Read the personality bytes using the Read Status command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param[out] personality Receives personality read from device.
      CmdResult readPersonality(Personality & personality) const;
      
      /// Update the status of a memory protection block using the Write Page Protection command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param[in] Desired protection status for the block.
      ///            It is not possible to disable existing protections.
      /// @param continuing True to continue a previous Write Page Protection command.
      ///                   False to begin a new command.
      CmdResult writeBlockProtection(const BlockProtection & protection);
      
      /// Update the status of a memory protection block using the Authenticated Write Page Protection command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param MacCoproc Coprocessor with Slave Secret to use for the operation.
      /// @param[in] newProtection New protection status to write.
      /// @param[in] oldProtection Existing protection status in device.
      /// @param continuing True to continue a previous Authenticated Write Page Protection command.
      ///                   False to begin a new command.
      CmdResult writeAuthBlockProtection(const ISha256MacCoproc & MacCoproc,
                                         const BlockProtection & newProtection,
                                         const BlockProtection & oldProtection);
      
      /// Write memory segment with authentication using the Authenticated Write Memory command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param MacCoproc Coprocessor to use for Write MAC computation.
      /// @param pageNum Page number for write operation.
      /// @param segmentNum Segment number within page for write operation.
      /// @param[in] newData New data to write to the segment.
      /// @param[in] oldData Existing data contained in the segment.
      /// @param continuing True to continue writing with the next sequential segment.
      ///                   False to begin a new command.
      CmdResult writeAuthSegment(const ISha256MacCoproc & MacCoproc,
                                 unsigned int pageNum,
                                 unsigned int segmentNum,
                                 const Segment & newData,
                                 const Segment & oldData,
                                 bool continuing = false);
      
      /// Write memory segment with authentication using the Authenticated Write Memory command.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param pageNum Page number for write operation.
      /// @param segmentNum Segment number within page for write operation.
      /// @param[in] newData New data to write to the segment.
      /// @param[in] mac Write MAC computed for this operation.
      /// @param continuing True to continue writing with the next sequential segment.
      ///                   False to begin a new command.
      CmdResult writeAuthSegmentMac(unsigned int pageNum,
                                    unsigned int segmentNum,
                                    const Segment & newData,
                                    const Mac & mac, 
                                    bool continuing = false);
      
    private: 
      static const unsigned int shaComputationDelayMs = 3;
      static const unsigned int eepromWriteDelayMs = 10;
      unsigned int secretEepromWriteDelayMs() const { return (lowVoltage ? 200 : 100); }

      Masters::OneWireMaster & m_OW_master;
      
      /// Read status bytes which are either personality or block protection.
      /// @note 1-Wire ROM selection should have already occurred.
      /// @param personality True to read personality or false to read block protection.
      /// @param allpages True to read all pages or false to read one page.
      /// @param pageNum Page number if reading block protection.
      /// @param rdbuf Buffer to receive data read from device.
      CmdResult readStatus(bool personality, bool allpages, unsigned int blockNum, uint8_t * rdbuf) const;
      
      /// Extends readStatus() to use the BlockProtection wrapper.
      /// @see readAllBlockProtection(BlockProtection (&)[DS28E15_BLOCKS])
      template <ProtectionBlocks blocks> CmdResult readAllBlockProtection(BlockProtection (&protection)[blocks]) const;
    };
  }
}

#endif