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.