Dallas Semiconductor 1-Wire API 1.00 Alpha: Class SHATransaction

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.dalsemi.onewire.application.sha
Class SHATransaction

    java.lang.Object
      |
      +--com.dalsemi.onewire.application.sha.SHATransaction

Direct Known Subclasses:
  SHADebit, SHADebitUnsigned

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

Version:
  1.00
See Also:
  `SHADebit`, `SHADebitUnsigned`

Field Summary
`static int` | `COPR_BIND_SECRET_FAILED`
`static int` | `COPR_COMPUTE_CHALLENGE_FAILED`
`static int` | `COPR_WRITE_DATAPAGE_FAILED`
`static int` | `COPR_WRITE_SCRATCHPAD_FAILED`
`static int` | `COPROCESSOR_FAILURE`
`static int` | `MATCH_SCRATCHPAD_FAILED`
`static int` | `NO_ERROR`
`static int` | `SHA_FUNCTION_FAILED`
`static int` | `USER_BAD_ACCOUNT_DATA`
`static int` | `USER_DATA_NOT_UPDATED`
`static int` | `USER_READ_AUTH_FAILED`
`static int` | `USER_WRITE_DATA_FAILED`

Constructor Summary
`SHATransaction(SHAiButtonCopr copr)` Creates a new SHATransaction, ensuring that reference to the coprocessor is saved and the errors are cleared.

Method Summary
`abstract boolean` | `executeTransaction(SHAiButtonUser user, boolean verifySuccess)` Performs the transaction.
`int` | `getLastCoprError()` Returns the error code for the last error in the transaction process.
`int` | `getLastError()` Returns the error code for the last error in the transaction process.
`abstract int` | `getParameter(int type)` Retrieves the value of a particular parameter for this transaction.
`abstract void` | `resetParameters()` Resets the value of all parameters for this transaction.
`abstract boolean` | `setParameter(int type, int param)` Sets a particular parameter for this transaction.
`abstract boolean` | `setupTransactionData(SHAiButtonUser user)` Setups initial transaction data on SHAiButtonUser.
`abstract boolean` | `verifyTransactionData(SHAiButtonUser user)` Verifies account data is valid for this service.
`abstract boolean` | `verifyUser(SHAiButtonUser user)` Verifies that SHAiButtonUser is a valid user of this service.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### NO_ERROR

    public static final int NO_ERROR

### SHA_FUNCTION_FAILED

    public static final int SHA_FUNCTION_FAILED

### MATCH_SCRATCHPAD_FAILED

    public static final int MATCH_SCRATCHPAD_FAILED

### COPR_WRITE_DATAPAGE_FAILED

    public static final int COPR_WRITE_DATAPAGE_FAILED

### COPR_WRITE_SCRATCHPAD_FAILED

    public static final int COPR_WRITE_SCRATCHPAD_FAILED

### COPR_BIND_SECRET_FAILED

    public static final int COPR_BIND_SECRET_FAILED

### COPR_COMPUTE_CHALLENGE_FAILED

    public static final int COPR_COMPUTE_CHALLENGE_FAILED

### COPROCESSOR_FAILURE

    public static final int COPROCESSOR_FAILURE

### USER_READ_AUTH_FAILED

    public static final int USER_READ_AUTH_FAILED

### USER_WRITE_DATA_FAILED

    public static final int USER_WRITE_DATA_FAILED

### USER_BAD_ACCOUNT_DATA

    public static final int USER_BAD_ACCOUNT_DATA

### USER_DATA_NOT_UPDATED

    public static final int USER_DATA_NOT_UPDATED

Constructor Detail

### SHATransaction

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

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

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

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

### 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

### 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 peformed.

### 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 peformed.

### 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 peformed.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD