Class SHATransaction

  • Direct Known Subclasses:
    SHADebit, SHADebitUnsigned, SHASoftAuth

    public abstract class SHATransaction
    extends java.lang.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:
    SHADebit, SHADebitUnsigned
    • Field Detail

      • MATCH_SCRATCHPAD_FAILED

        public static final int MATCH_SCRATCHPAD_FAILED
        See Also:
        Constant Field Values
      • COPR_WRITE_DATAPAGE_FAILED

        public static final int COPR_WRITE_DATAPAGE_FAILED
        See Also:
        Constant Field Values
      • COPR_WRITE_SCRATCHPAD_FAILED

        public static final int COPR_WRITE_SCRATCHPAD_FAILED
        See Also:
        Constant Field Values
      • COPR_BIND_SECRET_FAILED

        public static final int COPR_BIND_SECRET_FAILED
        See Also:
        Constant Field Values
      • COPR_COMPUTE_CHALLENGE_FAILED

        public static final int COPR_COMPUTE_CHALLENGE_FAILED
        See Also:
        Constant Field Values
      • lastError

        protected int lastError
        The last error that occurred during this transaction
      • copr

        protected SHAiButtonCopr copr
        The coprocessor used to complete this transaction
    • Constructor Detail

      • 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 Detail

      • 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.

      • 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.