Package com.dalsemi.onewire.application.sha

Class SHAiButtonUser

java.lang.Object
com.dalsemi.onewire.application.sha.SHAiButtonUser
Direct Known Subclasses:
SHAiButtonUser18, SHAiButtonUser33
public abstract class SHAiButtonUser extends Object

The abstract superclass for all users of a SHAiButton transaction system. The user in a SHA transaction system mainly consists of a page (or pages) of account data. The abstract superclass guarantees an interface for retrieving information about account data, as well as reading and writing that data.

SHAiButtonUser was defined for use with the DS1963S (family code 0x18) and the DS1961S (family code 0x33). The benefit to using our SHA iButtons in a transaction is for device authentication. Using a challenge-response protocol, the DS1961S and the DS1963S can authenticate themselves to the system before their actual account data is verified. But, if device authentication isn't important to your transaction, the SHAiButtonUser can be extended to support any 1-Wire memory device.

The format of user's account data is not specified by this class, only the interface for accessing it. Each different SHATransaction is free to implement whatever format is appropriate for the transaction type.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final byte[]
    accountData
    local cache of accountData
    protected int
    accountPageNumber
    page number account data is stored on
    protected byte[]
    address
    Cache of 1-Wire Address
    protected boolean
    forceOverdrive
    force 1-wire container into overdrive speed
    protected final byte[]
    fullBindCode
    maintains a cache of the fullBindCode, for later binding of coprocessor.
    protected final byte[]
    serviceFile
    used to construct appropriate string for OWFile constructor
    protected String
    strServiceFilename
    stores string name of user's service file
    protected int
    writeCycleCounter
    local cache of writeCycleCounter for data page

  • Constructor Summary

    Constructors
    Constructor
    Description
    SHAiButtonUser()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected boolean
    checkAccountPageInfo(OneWireContainer ibc)
    Asserts that proper account info exists for this SHAiButtonUser and establishes a buffer for caching account data.
    protected boolean
    createServiceFile(OneWireContainer owc, String filename, boolean formatDevice)
    Create's empty service file for the user with the given filename.
    String
    getAccountFilename()
    Returns the TMEX filename of the user's account data file.
    int
    getAccountPageNumber()
    Returns the page number of the first memory page where account data is stored.
    byte[]
    getAddress()
    Returns the 8 byte address of the OneWireContainer this SHAiButton refers to.
    void
    getAddress(byte[] data, int offset)
    Copies the 8 byte address of the OneWireContainer into the provided array starting at the given offset.
    void
    getAddress(byte[] data, int offset, int cnt)
    Copies the specified number of bytes from the address of the OneWireContainer into the provided array starting at the given offset.
    abstract byte
    getAuthorizationCommand()
    Returns a byte representing the appropriate authorization command for the coprocessor to use to authenticate this user.
    boolean
    getForceOverdrive()
    Reports whether or not the container is forced into overdrive.
    abstract void
    getFullBindCode(byte[] l_fullBindCode, int offset)
    This function creates the full 15-byte binding data for the coprocessor to use to recreate this user's secret on the copr's workspace page.
    abstract int
    getWriteCycleCounter()
    Returns the value of the write cycle counter for the page where the account data is stored.
    abstract boolean
    hasWriteCycleCounter()
    Returns true if this buttons account data is stored on a page that has a write cycle counter.
    abstract boolean
    readAccountData(byte[] dataBuffer, int offset)
    Reads the account data off the SHAiButton using a standard READ command.
    abstract int
    readAccountData(byte[] chlg, int chlgStart, byte[] dataBuffer, int dataStart, byte[] mac, int macStart)
    Reads the account data off the SHAiButton using a READ_AUTHENTICATE command.
    boolean
    refreshDevice()
    Refreshes eeprom SHA devices in case of weakly-programmed bits on the account page.
    void
    setForceOverdrive(boolean value)
    Sets whether or not the container should be forced into overdrive.
    abstract boolean
    setiButtonUser(byte[] address)
    Modifies this SHA iButton so that it refers to another device.
    abstract boolean
    setiButtonUser(DSPortAdapter adapter, byte[] address)
    Modifies this SHA iButton so that it refers to another device.
    String
    toString()
    Returns a string representing this SHAiButton.
    abstract boolean
    writeAccountData(byte[] dataBuffer, int offset)
    Writes the account data to the SHAiButton.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • address

      protected byte[] address
      Cache of 1-Wire Address

    • accountData

      protected final byte[] accountData
      local cache of accountData

    • accountPageNumber

      protected int accountPageNumber
      page number account data is stored on

    • serviceFile

      protected final byte[] serviceFile
      used to construct appropriate string for OWFile constructor

    • strServiceFilename

      protected String strServiceFilename
      stores string name of user's service file

    • fullBindCode

      protected final byte[] fullBindCode
      maintains a cache of the fullBindCode, for later binding of coprocessor.

    • writeCycleCounter

      protected int writeCycleCounter
      local cache of writeCycleCounter for data page

    • forceOverdrive

      protected boolean forceOverdrive
      force 1-wire container into overdrive speed

  • Constructor Details

    • SHAiButtonUser

      public SHAiButtonUser()

  • Method Details

    • getAccountPageNumber

      public int getAccountPageNumber()

      Returns the page number of the first memory page where account data is stored.

      Returns:
      page number where account data is stored.

    • getAccountFilename

      public String getAccountFilename()

      Returns the TMEX filename of the user's account data file.

      Returns:
      filename of user's account data file

    • getAddress

      public byte[] getAddress()

      Returns the 8 byte address of the OneWireContainer this SHAiButton refers to.

      Returns:
      8 byte array containing family code, address, and crc8 of the OneWire device.

    • getAddress

      public void getAddress(byte[] data, int offset)

      Copies the 8 byte address of the OneWireContainer into the provided array starting at the given offset.

      Parameters:
      data - array with at least 8 bytes after offset
      offset - the index at which copying starts

    • getAddress

      public void getAddress(byte[] data, int offset, int cnt)

      Copies the specified number of bytes from the address of the OneWireContainer into the provided array starting at the given offset.

      Parameters:
      data - array with at least cnt bytes after offset
      offset - the index at which copying starts
      cnt - the number of bytes to copy

    • setForceOverdrive

      public void setForceOverdrive(boolean value)
      Sets whether or not the container should be forced into overdrive.
      Parameters:
      value - if true, the container will be forced to overdrive

    • getForceOverdrive

      public boolean getForceOverdrive()
      Reports whether or not the container is forced into overdrive.
      Returns:
      if true, the container will be forced to overdrive

    • createServiceFile

      protected boolean createServiceFile(OneWireContainer owc, String filename, boolean formatDevice)

      Create's empty service file for the user with the given filename. Also, it populates accountPageNumber with the page that the service file is stored on.

      Parameters:
      owc - the 1-wire device where the service file will be created.
      filename - the filename of the service file.
      formatDevice - if true, the device is formatted before creating the service file.

    • checkAccountPageInfo

      protected boolean checkAccountPageInfo(OneWireContainer ibc)

      Asserts that proper account info exists for this SHAiButtonUser and establishes a buffer for caching account data.

      Parameters:
      ibc - the OneWireContainer whose account info is checked
      Returns:
      whether or not the device is initialized properly

    • setiButtonUser

      public abstract boolean setiButtonUser(DSPortAdapter adapter, byte[] address) throws OneWireException, OneWireIOException

      Modifies this SHA iButton so that it refers to another device. If this object already has an appropriate instance of OneWireContainer, that instance is updated with the new address.

      Parameters:
      adapter - The adapter that the device can be found on.
      address - The address of the 1-Wire device
      Returns:
      true if a valid account service file exists on this OneWireContainer18.
      Throws:
      OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
      OneWireException - on a communication or setup error with the 1-Wire adapter

    • setiButtonUser

      public abstract boolean setiButtonUser(byte[] address) throws OneWireException, OneWireIOException

      Modifies this SHA iButton so that it refers to another device. If this object does not already has an appropriate instance of OneWireContainer, it returns false immediately, because there is no adapter info available. Otherwise, it reuses the same adapter.

      Parameters:
      address - The address of the 1-Wire device
      Returns:
      true if a valid account service file exists on this OneWireContainer18.
      Throws:
      OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
      OneWireException - on a communication or setup error with the 1-Wire adapter

    • getWriteCycleCounter

      public abstract int getWriteCycleCounter() throws OneWireException, OneWireIOException

      Returns the value of the write cycle counter for the page where the account data is stored. If the write cycle counter has ever been retrieved, this returns the cached value. Otherwise, this method reads the value from the part.

      For devices that do not support write cycle counters, this method always returns -1.

      Returns:
      the value of the write cycle counter for the account data page.
      Throws:
      OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
      OneWireException - on a communication or setup error with the 1-Wire adapter

    • hasWriteCycleCounter

      public abstract boolean hasWriteCycleCounter()

      Returns true if this buttons account data is stored on a page that has a write cycle counter.

      Returns:
      true if account page has write cycle counter.

    • getFullBindCode

      public abstract void getFullBindCode(byte[] l_fullBindCode, int offset)

      This function creates the full 15-byte binding data for the coprocessor to use to recreate this user's secret on the copr's workspace page. This function is located in the SHAiButtonUser class to support binding codes for user buttons who use alternate techniques (such as the DS1961S) for secret computation.

      Parameters:
      offset - the offset into fullBindCode where copying should begin.
      bindCode - the 7-byte binding code from coprocessor's service file
      fullBindCode - the 15-byte full binding code to to be copied into the coprocessor's scratchpad. There should be 15 bytes available starting from the offset.

    • getAuthorizationCommand

      public abstract byte getAuthorizationCommand()

      Returns a byte representing the appropriate authorization command for the coprocessor to use to authenticate this user. For a DS1961S, the authentication command is AUTH_HOST, but for a DS1963S, the authentication command is VALIDATE_PAGE.

      Returns:
      byte indicating appropriate command for authenticating user

    • writeAccountData

      public abstract boolean writeAccountData(byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException

      Writes the account data to the SHAiButton. First, this function asserts that the account page number is known. The account data is copied from dataBuffer starting at the offset. If there are less than 32 bytes available to copy, this function only copies the bytes that are available.

      Parameters:
      dataBuffer - the buffer to copy the account data from
      offset - the index into the buffer where copying should begin
      Returns:
      whether or not the data write succeeded
      Throws:
      OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
      OneWireException - on a communication or setup error with the 1-Wire adapter

    • readAccountData

      public abstract boolean readAccountData(byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException

      Reads the account data off the SHAiButton using a standard READ command. First, this function asserts that the account page number is known as well as the length of the account file. The 32 byte account data page is copied into dataBuffer starting at the given offset.

      Parameters:
      dataBuffer - the buffer to copy the account data into
      offset - the index into the buffer where copying should begin
      Returns:
      whether or not the read was successful
      Throws:
      OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
      OneWireException - on a communication or setup error with the 1-Wire adapter

    • readAccountData

      public abstract int readAccountData(byte[] chlg, int chlgStart, byte[] dataBuffer, int dataStart, byte[] mac, int macStart) throws OneWireException, OneWireIOException

      Reads the account data off the SHAiButton using a READ_AUTHENTICATE command. First, this function asserts that the account page number is known as well as the length of the account file. Then it copies the 3 byte challenge to the scratchpad before sending the command for READ_AUTHENTICATE. The 32 byte account data page is copied into dataBuffer starting at dataStart.

      In addition to the account data, this function also returns a calculated MAC. The MAC requires 20 bytes after the start index. The return value is the write cycle counter value for the account data page

      Parameters:
      chlg - the buffer containing a 3-byte random challenge.
      chlgStart - the index into the buffer where the 3 byte challenge begins.
      dataBuffer - the buffer to copy the account data into
      dataStart - the index into the buffer where copying should begin
      mac - the buffer to copy the resulting Message Authentication Code
      macStart - the index into the mac buffer to start copying
      Returns:
      the value of the write cycle counter for the page
      Throws:
      OneWireIOException - on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
      OneWireException - on a communication or setup error with the 1-Wire adapter

    • refreshDevice

      public boolean refreshDevice() throws OneWireException, OneWireIOException
      Refreshes eeprom SHA devices in case of weakly-programmed bits on the account page.
      Returns:
      true if the refresh was successful
      Throws:
      OneWireException
      OneWireIOException

    • toString

      public String toString()

      Returns a string representing this SHAiButton.

      Overrides:
      toString in class Object
      Returns:
      a string containing the 8-byte address of this 1-Wire device.