Package com.dalsemi.onewire.application.sha

Class SHATransaction

java.lang.Object
com.dalsemi.onewire.application.sha.SHATransaction
Direct Known Subclasses:
SHADebit, SHADebitUnsigned, SHASoftAuth
public abstract class SHATransaction extends Object

Abstract super class for all SHA Transactions. Typical SHA transactions might be something like an account debit application, a door access control system, or a web-based authentication servlet. The SHATransaction super class contains the bare minimum functionality necessary for the steps involved in most SHA transaction applications.

The first characteristic of a SHA Transaction is that it is tied to an immutable SHAiButtonCopr, used for data signing and recreating user authentication responses. The SHA Transaction guarantees an interface for initializing account transaction data (setupTransactionData), verifying that the transaction data has not been tampered with (verifyTransactionData), performing the transaction and updating the data (executeTransaction), and validating a user with a challenge-response authentication protocol (verifyUser).

In addition, all transactions are characterized by certain parameters (i.e. how much to debit from the user or what level of access is being requested from the system). The interface for retrieving and setting these parameters is provided through the generic getParameter and setParameter.

See Also:

  • Field Details

    • NO_ERROR

      public static final int NO_ERROR
      See Also:

    • SHA_FUNCTION_FAILED

      public static final int SHA_FUNCTION_FAILED
      See Also:

    • MATCH_SCRATCHPAD_FAILED

      public static final int MATCH_SCRATCHPAD_FAILED
      See Also:

    • COPR_WRITE_DATAPAGE_FAILED

      public static final int COPR_WRITE_DATAPAGE_FAILED
      See Also:

    • COPR_WRITE_SCRATCHPAD_FAILED

      public static final int COPR_WRITE_SCRATCHPAD_FAILED
      See Also:

    • COPR_BIND_SECRET_FAILED

      public static final int COPR_BIND_SECRET_FAILED
      See Also:

    • COPR_COMPUTE_CHALLENGE_FAILED

      public static final int COPR_COMPUTE_CHALLENGE_FAILED
      See Also:

    • COPROCESSOR_FAILURE

      public static final int COPROCESSOR_FAILURE
      See Also:

    • USER_READ_AUTH_FAILED

      public static final int USER_READ_AUTH_FAILED
      See Also:

    • USER_WRITE_DATA_FAILED

      public static final int USER_WRITE_DATA_FAILED
      See Also:

    • USER_BAD_ACCOUNT_DATA

      public static final int USER_BAD_ACCOUNT_DATA
      See Also:

    • USER_DATA_NOT_UPDATED

      public static final int USER_DATA_NOT_UPDATED
      See Also:

    • lastError

      protected int lastError
      The last error that occurred during this transaction

    • copr

      protected SHAiButtonCopr copr
      The coprocessor used to complete this transaction

  • Constructor Details

    • SHATransaction

      protected SHATransaction()

      User applications should not instantiate this class without an instance of a coprocessor.

    • SHATransaction

      protected SHATransaction(SHAiButtonCopr copr)

      Creates a new SHATransaction, ensuring that reference to the coprocessor is saved and the errors are cleared.

  • Method Details

    • getLastError

      public int getLastError()

      Returns the error code for the last error in the transaction process.

    • getLastCoprError

      public int getLastCoprError()

      Returns the error code for the last error in the transaction process.

    • setupTransactionData

      public abstract boolean setupTransactionData(SHAiButtonUser user) throws OneWireException, OneWireIOException

      Setups initial transaction data on SHAiButtonUser. This step creates the account data file, signs it with the coprocessor, and writes it to the iButton.

      Throws:
      OneWireException
      OneWireIOException

    • verifyUser

      public abstract boolean verifyUser(SHAiButtonUser user) throws OneWireException, OneWireIOException

      Verifies that SHAiButtonUser is a valid user of this service. This step writes a three byte challenge to the SHAiButtonUser before doing an authenticated read of the account data. The returned MAC is verified using the system authentication secret on the coprocessor. If the MAC matches that generated by the coprocessor, this function returns true.

      Throws:
      OneWireException
      OneWireIOException

    • verifyTransactionData

      public abstract boolean verifyTransactionData(SHAiButtonUser user) throws OneWireException, OneWireIOException

      Verifies account data is valid for this service. The user's account data is recreated on the coprocessor and signed using the system signing secret. If the recreated signature matches the signature in the account data, the account data is valid.

      Throws:
      OneWireException
      OneWireIOException

    • executeTransaction

      public abstract boolean executeTransaction(SHAiButtonUser user, boolean verifySuccess) throws OneWireException, OneWireIOException

      Performs the transaction. For any given transaction type, this step would involve updating any necessary account data, signing the account data using the coprocessor's system signing secret, and writing the updated account data to the user iButton

      Throws:
      OneWireException
      OneWireIOException

    • setParameter

      public abstract boolean setParameter(int type, int param)

      Sets a particular parameter for this transaction. Parameters are specified in the class documentation for the specific type of transaction that is being performed.

    • getParameter

      public abstract int getParameter(int type)

      Retrieves the value of a particular parameter for this transaction. Parameters are specified in the class documentation for the specific type of transaction that is being performed.

    • resetParameters

      public abstract void resetParameters()

      Resets the value of all parameters for this transaction. Parameters are specified in the class documentation for the specific type of transaction that is being performed.