Package com.dalsemi.onewire.application.sha

Class SHAiButtonCopr

java.lang.Object
com.dalsemi.onewire.application.sha.SHAiButtonCopr
Direct Known Subclasses:
SHAiButtonCoprVM
public class SHAiButtonCopr extends Object

Class for holding instances of SHA iButton Coprocessors involved in SHA Transactions. The Coprocessor is used for digitally signing transaction data as well as generating random challenges for users and verifying their response.

A DS1963S SHA iButton can be a SHAiButtonCopr or a SHAiButtonUser. A Coprocessor iButton verifiessignatures and signs data for User iButtons. A Coprocessor might be located inside a vending machine, where a person would bring their User iButton. When the User iButton is pressed to the Blue Dot to perform a transaction, the Coprocessor would first verify that this button belongs to the system, i.e. that it knows the same authentication secret (example: a Visa terminal making sure the iButton had a Visa account installed). Then the Coprocessor would verify the signed data, probably money, to make sure it was valid. If someone tried to overwrite the money file, even with a previously valid money file (an attempt to 'restore' a previous amount of money), the signed file would be invalid because the signature includes the write cycle counter, which is incremented every time a page is written to. The write cycle counter is read-only and does not roll over, so the previous amount of money could not be restored by rolling the write counter. The Coprocessor verifies the money, then signs a new data file that contains the new amount of money.

There are two secrets involved with the transaction process. The first secret is the authentication secret. It is used to validate a User iButton to a system. The Coprocessor iButton has the system authentication secret installed. On User iButtons, the system authentication secret is merged with binding data and the unique address of the User iButton to create a unique device authentication secret. The second secret is a signing secret. This secret only exists on the Coprocessor iButton, and is used to sign and verify transaction data (i.e. money). These secrets are inaccessible outside the iButton. Once they are installed, they cannot be retrieved.

This class makes use of several performance enhancements for TINI. For instance, most methods are synchronized to access instance variable byte arrays rather than creating new byte arrays every time a transaction is performed. This could hurt performance in multi-threaded applications, but the usefulness of having several threads contending to talk to a single iButton is questionable since the methods in com.dalsemi.onewire.adapter.DSPortAdapter beginExclusive(boolean) and endExclusive() should be used.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected byte[]
    address
    Cache of 1-Wire Address
    protected int
    authPageNumber
    Page used for generating user authentication secret.
    protected String
    auxData
    Any auxiliary data stored on this coprocessor
    static final int
    BIND_SECRET_FAILED
     
    protected byte[]
    bindCode
    7 bytes of binding data for scratchpad to bind secret installation
    protected byte[]
    bindData
    32 bytes of binding data to bind secret installation
    static final int
    COPY_SCRATCHPAD_FAILED
     
    protected boolean
    DS1961Scompatible
    Specifies whether or not this coprocessor is compatible with the DS1961S.
    protected int
    encCode
    Code used to specify encryption type.
    static final int
    ERASE_SCRATCHPAD_FAILED
     
    protected byte[]
    filename
    Filename, including extension, for user's service file
    protected OneWireContainer18
    ibc
    Reference to the OneWireContainer
    protected byte[]
    initialSignature
    20 byte initial signature, used for signing user account data
    protected int
    lastError
    Last error code raised
    static final int
    MATCH_SCRATCHPAD_FAILED
     
    static final int
    NO_ERROR
     
    protected String
    providerName
    The Provider name of the coprocessor's service
    static final int
    SHA_FUNCTION_FAILED
     
    protected byte[]
    signingChallenge
    3 byte challenge, used for signing user account data
    protected int
    signPageNumber
    Page used for signing user account data.
    protected int
    version
    Code used to specify encryption type.
    static final int
    WRITE_DATA_PAGE_FAILED
     
    static final int
    WRITE_SCRATCHPAD_FAILED
     
    protected int
    wspcPageNumber
    Page used for generating user's validation MAC.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    SHAiButtonCopr()
    No default construct for user apps.
     
    SHAiButtonCopr(OneWireContainer18 owc, String coprFilename)
    Sets up this coprocessor object based on the contents of the file coprFilename stored on owc.
     
    SHAiButtonCopr(OneWireContainer18 l_owc, String coprFilename, boolean l_formatDevice, int l_signPageNumber, int l_authPageNumber, int l_wspcPageNumber, int l_version, int l_encCode, byte l_serviceFileExt, byte[] l_serviceFilename, byte[] l_providerName, byte[] l_bindData, byte[] l_bindCode, byte[] l_auxData, byte[] l_initialSignature, byte[] l_signingChlg, byte[] l_signingSecret, byte[] l_authSecret)
    Sets up this coprocessor object based on the provided parameters and saves all of these parameters as the contents of the file coprFilename stored on owc.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    createDataSignature(byte[] accountData, byte[] signScratchpad, byte[] mac_buffer, int macStart)
    Given a 32-byte array for page data and a 32-byte array for scratchpad content, this function will create a 20-byte signature for the data based on SHA-1.
    boolean
    createDataSignatureAuth(byte[] accountData, byte[] signScratchpad, byte[] mac_buffer, int macStart, byte[] fullBindCode)
    Creates a data signature, but instead of using the signing secret, it uses the authentication secret, bound for a particular button.
    protected void
    fromStream(InputStream is)
    Configuration helper.
    boolean
    generateChallenge(int offset, byte[] ch, int start)
    Generates a 3 byte random challenge in the iButton, sufficient to be used as a challenge to be answered by a User iButton.
    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.
    int
    getAuthenticationPageNumber()
    Returns the page number used by this coprocessor for storing system authentication secret and recreating user's authentication secret.
    String
    getAuxilliaryData()
    Returns a string representing the auxiliary data associated with this coprocessor's service.
    byte[]
    getBindCode()
    Returns 7 byte binding code for finalizing secret installation on user buttons.
    void
    getBindCode(byte[] data, int offset)
    Copies 7 byte binding code for finalizing secret installation on user buttons.
    byte[]
    getBindData()
    Returns 32 byte binding data for finalizing secret installation on user buttons.
    void
    getBindData(byte[] data, int offset)
    Copies 32 byte binding data for finalizing secret installation on user buttons.
    int
    getEncryptionCode()
    Returns an integer representing the encryption code for this coprocessor.
    void
    getFilename(byte[] l_filename, int offset)
    Copies the filename (used for storing account data on user buttons) into the specified array starting at the specified offset.
    byte
    getFilenameExt()
    Returns the extension of the filename used for storing account data on user buttons.
    byte[]
    getInitialSignature()
    Returns the 20-byte initial signature used by this coprocessor for signing account data.
    void
    getInitialSignature(byte[] data, int offset)
    Copies the 20-byte initial signature used by this coprocessor for signing account data into the specified array starting at the specified offset.
    int
    getLastError()
    Returns error code matching last error encountered by the coprocessor.
    String
    getProviderName()
    Returns a string representing the Provider name associated with this coprocessor's service.
    byte[]
    getSigningChallenge()
    Returns the 3-byte signing challenge used by this coprocessor for data validation.
    void
    getSigningChallenge(byte[] data, int offset)
    Copies the 3-byte signing challenge used by this coprocessor for data validation into the specified array starting at the specified offset.
    int
    getSigningPageNumber()
    Returns the page number used by this coprocessor for signing account data.
    int
    getVersion()
    Returns the version number of this service.
    int
    getWorkspacePageNumber()
    Returns the page number used by this coprocessor for regenerating the user authentication.
    boolean
    isDS1961Scompatible()
    Returns a boolean indicating whether or not this coprocessor's secret's were formatted for compatibility with the DS1961S.
    static byte[]
    reformatFor1961S(byte[] auth_secret)
    Static method that reformats the inputted authentication secret so it is compatible with the DS1961S.
    protected void
    toStream(OutputStream os)
    Configuration saving method.
    String
    toString()
    Returns a string representing the 1-Wire address of this SHAiButton.
    boolean
    verifyAuthentication(byte[] fullBindCode, byte[] pageData, byte[] scratchpad, byte[] verify_mac, byte authCmd)
    Determines if a SHAiButtonUser belongs to the system defined by this Coprocessor iButton.See the usage example in this class for initializing a Coprocessor iButton.
    boolean
    verifySignature(byte[] pageData, byte[] scratchpad, byte[] verify_mac)
    Verifies a User iButton's signed data on this Coprocessor iButton.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • NO_ERROR

      public static final int NO_ERROR
      See Also:

    • WRITE_DATA_PAGE_FAILED

      public static final int WRITE_DATA_PAGE_FAILED
      See Also:

    • WRITE_SCRATCHPAD_FAILED

      public static final int WRITE_SCRATCHPAD_FAILED
      See Also:

    • MATCH_SCRATCHPAD_FAILED

      public static final int MATCH_SCRATCHPAD_FAILED
      See Also:

    • ERASE_SCRATCHPAD_FAILED

      public static final int ERASE_SCRATCHPAD_FAILED
      See Also:

    • COPY_SCRATCHPAD_FAILED

      public static final int COPY_SCRATCHPAD_FAILED
      See Also:

    • SHA_FUNCTION_FAILED

      public static final int SHA_FUNCTION_FAILED
      See Also:

    • BIND_SECRET_FAILED

      public static final int BIND_SECRET_FAILED
      See Also:

    • lastError

      protected int lastError
      Last error code raised

    • ibc

      protected OneWireContainer18 ibc
      Reference to the OneWireContainer

    • address

      protected byte[] address
      Cache of 1-Wire Address

    • authPageNumber

      protected int authPageNumber
      Page used for generating user authentication secret.

    • auxData

      protected String auxData
      Any auxiliary data stored on this coprocessor

    • bindCode

      protected byte[] bindCode
      7 bytes of binding data for scratchpad to bind secret installation

    • bindData

      protected byte[] bindData
      32 bytes of binding data to bind secret installation

    • DS1961Scompatible

      protected boolean DS1961Scompatible
      Specifies whether or not this coprocessor is compatible with the DS1961S. This entails the use of a specifically padded authentication secret.

    • encCode

      protected int encCode
      Code used to specify encryption type.

    • filename

      protected byte[] filename
      Filename, including extension, for user's service file

    • initialSignature

      protected byte[] initialSignature
      20 byte initial signature, used for signing user account data

    • providerName

      protected String providerName
      The Provider name of the coprocessor's service

    • signingChallenge

      protected byte[] signingChallenge
      3 byte challenge, used for signing user account data

    • signPageNumber

      protected int signPageNumber
      Page used for signing user account data.

    • version

      protected int version
      Code used to specify encryption type.

    • wspcPageNumber

      protected int wspcPageNumber
      Page used for generating user's validation MAC.

  • Constructor Details

    • SHAiButtonCopr

      protected SHAiButtonCopr()

      No default construct for user apps. Coprocessors, unlike users, are immutable classes, so there is no setiButton for User applications.

      See Also:

    • SHAiButtonCopr

      public SHAiButtonCopr(OneWireContainer18 l_owc, String coprFilename, boolean l_formatDevice, int l_signPageNumber, int l_authPageNumber, int l_wspcPageNumber, int l_version, int l_encCode, byte l_serviceFileExt, byte[] l_serviceFilename, byte[] l_providerName, byte[] l_bindData, byte[] l_bindCode, byte[] l_auxData, byte[] l_initialSignature, byte[] l_signingChlg, byte[] l_signingSecret, byte[] l_authSecret) throws OneWireException, OneWireIOException

      Sets up this coprocessor object based on the provided parameters and saves all of these parameters as the contents of the file coprFilename stored on owc. Then, the system secret and authentication secret are installed on the coprocessor button.

      For the proper format of the coprocessor data file, see the document entitled "Implementing Secured D-Identification and E-Payment Applications using SHA iButtons". For the format of TMEX file structures, see Application Note 114.

      Parameters:
      l_owc - The DS1963S used as a coprocessor.
      coprFilename - The TMEX filename where coprocessor configuration data is stored. Usually, "COPR.0".
      l_formatDevice - boolean indicating whether or not the TMEX filesystem of this device should be formatted before the coprocessor data file is stored.
      l_signPageNumber - page number used for signing user account data. (Should be page 8, but page 0 is acceptable if you don't need the TMEX directory structure)
      l_authPageNumber - page number used for recreating user secret.
      l_wspcPageNumber - page number used for storing user secret and recreating authentication MAC.
      l_version - version of the service provided by this coprocessor.
      l_encCode - refers to a type of encryption used for user account data stored on user buttons.
      l_serviceFileExt - the file extension used for the service file. (An extension of decimal 102 is reserved for Money files).
      l_serviceFilename - the 4-byte name of the user's account data file.
      l_providerName - the name of the provider of this service
      l_bindData - the binding data used to finalize secret installation on user buttons.
      l_bindCode - the binding code used to finalize secret installation on user buttons.
      l_auxData - any auxiliary or miscellaneous data to be stored on the coprocessor.
      l_initialSignature - the 20-byte initial MAC placed in user account data before generating actual MAC.
      l_signingChlg - the 3-byte challenge used for signing user account data.
      l_signingSecret - the system signing secret used by the service being installed on this coprocessor.
      l_authSecret - the system authentication secret used by the service being installed on this coprocessor.
      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
      See Also:

    • SHAiButtonCopr

      public SHAiButtonCopr(OneWireContainer18 owc, String coprFilename) throws OneWireException, OneWireIOException

      Sets up this coprocessor object based on the contents of the file coprFilename stored on owc. This sets all the properties of the object as a consequence of what's in the coprocessor file.

      For the proper format of the coprocessor data file, see the document entitled "Implementing Secured D-Identification and E-Payment Applications using SHA iButtons". For the format of TMEX file structures, see Application Note 114.

      Parameters:
      owc - The DS1963S used as a coprocessor
      coprFilename - The TMEX filename where coprocessor configuration data is stored. Usually, "COPR.0".
      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
      See Also:

  • Method Details

    • 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

    • getAuthenticationPageNumber

      public int getAuthenticationPageNumber()

      Returns the page number used by this coprocessor for storing system authentication secret and recreating user's authentication secret. The authentication secret stays constant, while the new secret is copied on to the secret corresponding to the workspace page.

      Returns:
      page number used for system authentication secret
      See Also:

    • getAuxilliaryData

      public String getAuxilliaryData()

      Returns a string representing the auxiliary data associated with this coprocessor's service.

      Returns:
      the auxiliary data of this coprocessor's service

    • getBindCode

      public byte[] getBindCode()

      Returns 7 byte binding code for finalizing secret installation on user buttons. This is copied into the user's scratchpad, along with 8 other bytes of binding data (see bindSecretToiButton) for finalizing the secret and making it unique to the button.

      Returns:
      the binding code for user's scratchpad
      See Also:

    • getBindCode

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

      Copies 7 byte binding code for finalizing secret installation on user buttons. This is copied into the user's scratchpad, along with 8 other bytes of binding data (see bindSecretToiButton) for finalizing the secret and making it unique to the button.

      Parameters:
      data - array for copying the binding code for user's scratchpad
      offset - the index at which to start copying.
      See Also:

    • getBindData

      public byte[] getBindData()

      Returns 32 byte binding data for finalizing secret installation on user buttons. This is copied into the user's account data page (see bindSecretToiButton) for finalizing the secret and making it unique to the button.

      Returns:
      the binding data for user's data page
      See Also:

    • getBindData

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

      Copies 32 byte binding data for finalizing secret installation on user buttons. This is then copied into the user's account data page (see bindSecretToiButton) for finalizing the secret and making it unique to the button.

      Parameters:
      data - array for copying the binding data for user's data page
      offset - the index at which to start copying.
      See Also:

    • getEncryptionCode

      public int getEncryptionCode()

      Returns an integer representing the encryption code for this coprocessor. No handling of specific encryption codes are in place with this API, but could be added easily at the SHATransaction layer.

      Returns:
      an integer representing type of encryption for user data.

    • getFilename

      public void getFilename(byte[] l_filename, int offset)

      Copies the filename (used for storing account data on user buttons) into the specified array starting at the specified offset.

      Parameters:
      l_filename - the array into which the filename will be copied.
      offset - the starting index for copying the filename.

    • getFilenameExt

      public byte getFilenameExt()

      Returns the extension of the filename used for storing account data on user buttons. If the type of this service is an e-cash application, the file extension will be decimal 102.

      Returns:
      proper file extension for user's account data file.

    • getInitialSignature

      public byte[] getInitialSignature()

      Returns the 20-byte initial signature used by this coprocessor for signing account data.

      Returns:
      20-byte initial signature.

    • getInitialSignature

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

      Copies the 20-byte initial signature used by this coprocessor for signing account data into the specified array starting at the specified offset.

      Parameters:
      data - array for copying the 20-byte initial signature.
      offset - the index at which to start copying.

    • getLastError

      public int getLastError()

      Returns error code matching last error encountered by the coprocessor. An error code of zero implies NO_ERROR.

      Returns:
      the error code, zero for none.

    • getProviderName

      public String getProviderName()

      Returns a string representing the Provider name associated with this coprocessor's service.

      Returns:
      the name of the provider's service.

    • getSigningChallenge

      public byte[] getSigningChallenge()

      Returns the 3-byte signing challenge used by this coprocessor for data validation.

      Returns:
      3-byte challenge

    • getSigningChallenge

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

      Copies the 3-byte signing challenge used by this coprocessor for data validation into the specified array starting at the specified offset.

      Parameters:
      data - the array for copying the 3-byte challenge.
      offset - the index at which to start copying.

    • getSigningPageNumber

      public int getSigningPageNumber()

      Returns the page number used by this coprocessor for signing account data.

      Returns:
      page number used for signing

    • getVersion

      public int getVersion()

      Returns the version number of this service.

      Returns:
      version number for service.

    • getWorkspacePageNumber

      public int getWorkspacePageNumber()

      Returns the page number used by this coprocessor for regenerating the user authentication. This page is the target page for bindSecretToiButton when trying to reproduce a user's authentication secret.

      Returns:
      page number used for regenerating user authentication.
      See Also:

    • isDS1961Scompatible

      public boolean isDS1961Scompatible()

      Returns a boolean indicating whether or not this coprocessor's secret's were formatted for compatibility with the DS1961S.

      Returns:
      true if this coprocessor can authenticate a DS1961S using it's system authentication secret.
      See Also:

    • createDataSignature

      public boolean createDataSignature(byte[] accountData, byte[] signScratchpad, byte[] mac_buffer, int macStart) throws OneWireException, OneWireIOException

      Given a 32-byte array for page data and a 32-byte array for scratchpad content, this function will create a 20-byte signature for the data based on SHA-1. The format of the calculation of the data signature is as follows: First 4-bytes of signing secret, 32-bytes of accountData, 12 bytes of scratchpad data starting at index 8, last 4-bytes of signing secret, 3 bytes of scratchpad data starting at index 20, and the rest is padding as specified for standard SHA-1. This is all laid out, in detail, in the DS1963S data sheet.

      The resulting 20-byte signature is copied into mac_buffer starting at macStart. If you're updating a signature that already exists in the accountData array, it is acceptable to call the method like so: 

         copr.createDataSignature(accountData, spad, accountData, 8);
      assuming that the signature starts at index 8 of the accountData array.

      Parameters:
      accountData - the 32-byte data page for which the signature is generated.
      signScratchpad - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
      mac_buffer - used to return the 20-byte signature generated by signing the page using the coprocessor's system signing secret.
      macStart - the offset into mac_buffer where copying should start.
      Returns:
      true if successful, false if an error occurred (use getLastError() for more information on the type of error)
      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
      See Also:

    • createDataSignatureAuth

      public boolean createDataSignatureAuth(byte[] accountData, byte[] signScratchpad, byte[] mac_buffer, int macStart, byte[] fullBindCode) throws OneWireException, OneWireIOException

      Creates a data signature, but instead of using the signing secret, it uses the authentication secret, bound for a particular button.

      fullBindCode can be null if the secret is already bound and in the signing page.

      Parameters:
      accountData - the 32-byte data page for which the signature is generated.
      signScratchpad - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
      mac_buffer - used to return the 20-byte signature generated by signing the page using the coprocessor's system signing secret.
      macStart - the offset into mac_buffer where copying should start.
      fullBindCode - used to recreate the user iButton's unique secret
      Returns:
      true if successful, false if an error occurred (use getLastError() for more information on the type of error)
      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
      See Also:

    • generateChallenge

      public boolean generateChallenge(int offset, byte[] ch, int start) throws OneWireIOException, OneWireException

      Generates a 3 byte random challenge in the iButton, sufficient to be used as a challenge to be answered by a User iButton. The user answers the challenge with an authenticated read of it's account data.

      The DS1963S will generate 20 bytes of pseudo random data, though only 3 bytes are needed for the challenge. Programs can add more 'randomness' by selecting different bytes from the 20 bytes of random data using the offset parameter.

      The random number generator is actually the DS1963S's SHA engine, which requires page data to compute a hash. Select a page number with the page_number parameter.

      Parameters:
      offset - offset into the 20 random bytes to draw random data from (must be in range 0-16)
      ch - buffer for the challenge to be returned (must be of length 3 or more)
      start - the starting index into array ch to begin copying the challenge bytes.
      Returns:
      true if successful, false if an error occurred (use getLastError() for more information on the type of error)
      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
      See Also:

    • verifyAuthentication

      public boolean verifyAuthentication(byte[] fullBindCode, byte[] pageData, byte[] scratchpad, byte[] verify_mac, byte authCmd) throws OneWireIOException, OneWireException

      Determines if a SHAiButtonUser belongs to the system defined by this Coprocessor iButton.See the usage example in this class for initializing a Coprocessor iButton.

      The first step in user authentication is to recreate the user's unique secret on the coprocessor button using bindSecretToiButton(int,byte[],byte[],int). Then the coprocessor signs the pageData to produce a MAC. If the MAC matches that produced by the user, the user belongs to the system.

      The TMEX formatted page with the user's account data is in the 32-byte parameter pageData. If the verification is successful, the data data signature must still be verified with the verifySignature() method.

      Failure of this method does not necessarily mean that the User iButton does not belong to the system. It is possible that a communication disruption here could cause a CRC error that would be indistinguishable from a failed authentication. However, repeated attempts should reveal whether it was truly a communication problem or a User iButton that does not belong to the system.

      Parameters:
      fullBindCode - 15-byte binding code used to recreate user iButtons unique secret in the coprocessor.
      pageData - 32-byte buffer containing the data page holding the user's account data.
      scratchpad - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
      verify_mac - the 20-byte buffer containing the user's authentication response to the coprocessor's challenge.
      Returns:
      true if the operation was successful and the user's MAC matches that generated by the coprocessor.
      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
      See Also:

    • verifySignature

      public boolean verifySignature(byte[] pageData, byte[] scratchpad, byte[] verify_mac) throws OneWireIOException, OneWireException

      Verifies a User iButton's signed data on this Coprocessor iButton. The Coprocessor must recreate the signature based on the data in the file and the contents of the given scratchpad, and then match that with the signature passed in verify_mac.

      Parameters:
      pageData - the full 32 byte TMEX file from the User iButton (from verifyAuthentication) with the
      scratchpad - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
      verify_mac - the 20-byte buffer containing the signature the user had stored with the account data file.
      Returns:
      true if the data file is valid, false if an error occurred (use getLastError() for more information on the type of error)
      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
      See Also:

    • toString

      public String toString()
      Returns a string representing the 1-Wire address of this SHAiButton.
      Overrides:
      toString in class Object
      Returns:
      a string containing the 8-byte address of this 1-Wire device.

    • fromStream

      protected void fromStream(InputStream is) throws IOException
      Configuration helper. Used also by Coprocessor VM
      Throws:
      IOException

    • toStream

      protected void toStream(OutputStream os) throws IOException
      Configuration saving method. Used also by Coprocessor VM
      Throws:
      IOException

    • reformatFor1961S

      public static byte[] reformatFor1961S(byte[] auth_secret)

      Static method that reformats the inputted authentication secret so it is compatible with the DS1961S. This means that for every group of 47 bytes in the secret, bytes at indices 32-35 and indices 44-46 are all set to 0xFF. Check the format for secret generation in the DS1961S data sheet to verify format of digest buffer.

      Note that if a coprocessor button uses this formatted secret, this function should be called for all user buttons including the DS1963S and DS1961S to ensure compatibility

      Parameters:
      auth_secret - the authentication secret to be reformatted.
      Returns:
      a reformatted authentication secret, with the appropriate padding for DS1961S interaction.