com.dalsemi.onewire.application.sha
Class SHADebitUnsigned

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

public class SHADebitUnsigned

extends SHATransaction

This class implements an account debit application for unsigned SHA Transactions. Account data is stored on user iButtons with no digital signature (unlike SHADebit which signs the data with a coprocessor iButton). The signature is still stored with the file, for consistency among other SHA applications, but is not updated when the account data is updated.

You may be wondering, "Why use a SHA transaction interface for unsigned account data?" The answer is for increasing transaction times with the DS1961S user iButton. All data writes to the DS1961S require knowledge of the iButton's unique secret, which prevents tampering with the account data. Since a data signature on account data is designed for the same purpose, it is removed from this transaction to remove redundancy and achieve better performance with the DS1961S.

Account data consists of the following:

• 1 byte: Length of the account file
• 2 bytes: Transaction ID
• 2 bytes: Account Money Conversion Factor
• 3 bytes: Account Balance
• 20 bytes: Account Data Signature (constant data)
• 1 byte: Account data type (dynamic or static)
• 1 byte: File continuation pointer
• 2 bytes: CRC16 of entire 30 bytes seeded with the page number
• 32 bytes Total

A typical use case for this class might be as follows:

   OneWireContainer18 coprOWC18 = new OneWireContainer18(adapter,address);

   //COPR.0 is the filename for coprocessor service data
   SHAiButtonCopr copr = new SHAiButtonCopr(coprOWC18,"COPR.0");

   //Initial amount for new users is $100, and debit amount is 50 cents
   SHATransaction trans = new SHADebitUnsigned(copr, 10000, 50);

   OneWireContainer33 owc33 = new OneWireContainer33(adapter, userAddress);

   //The following constructor erases all transaction data from the user and
   //installs the system authentication secret on the user iButton.
   //The second instance of coprocessor is used for write-authorization.  If you're
   //not using the system coprocessor for data signing, it can be re-used for this
   //purpose.
   SHAiButtonUser user = new SHAiButtonUser33(copr, copr, owc33, true, authSecret);

   //creates account data on iButton
   if(trans.setupTransactionData(user))
      System.out.println("Account data installed successfully");
   else
      System.out.println("Account data installation failed");

   //... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...

   //verifies authentication response of user iButton from "challenge"
   if(trans.verifyUser(user))
   {
      System.out.println("User Verified Successfully");

      //Checks to see that account balance is greater than zero
      if(trans.verifyTransactionData(user))
      {
         System.out.println("Account Data Verified Successfully");

         //performs the debit and writes the new account balance
         if(trans.executeTransaction(user))
         {
            System.out.println("Account debited.");
            System.out.println("New Balance: " +
               trans.getParameter(SHADebit.USER_BALANCE));
         }
      }
   }

   //... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...

   if(trans.getLastError()!=0)
   {
      System.err.println("Error code: " + trans.getLastError());
   }
 

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.

Version:

1.00

See Also:

SHATransaction, SHAiButtonCopr, SHAiButtonUser

Field Summary

static int	DEBIT_AMOUNT Update the amount this transaction will debit
static int	INITIAL_AMOUNT Update the amount for initial account balance
static int	USER_BALANCE Retrieve the amount for user's current balance

Fields inherited from class com.dalsemi.onewire.application.sha.SHATransaction

COPR_BIND_SECRET_FAILED, COPR_COMPUTE_CHALLENGE_FAILED, COPR_WRITE_DATAPAGE_FAILED, COPR_WRITE_SCRATCHPAD_FAILED, COPROCESSOR_FAILURE, MATCH_SCRATCHPAD_FAILED, NO_ERROR, SHA_FUNCTION_FAILED, USER_BAD_ACCOUNT_DATA, USER_DATA_NOT_UPDATED, USER_READ_AUTH_FAILED, USER_WRITE_DATA_FAILED

Constructor Summary

SHADebitUnsigned(SHAiButtonCopr copr)
SHADebitUnsigned constructor.

SHADebitUnsigned(SHAiButtonCopr copr, int initialAmount, int debitAmount)
SHADebitUnsigned constructor.

Method Summary

boolean	executeTransaction(SHAiButtonUser user, boolean verifySuccess) Performs the unsigned debit, subtracting the debit amount from the user's balance and storing the new, unsigned account data on the user's iButton.
int	getParameter(int type) Retrieves the value of a particular parameter for this debit transaction.
void	resetParameters() Resets all transaction parameters to default values
boolean	setParameter(int type, int param) Sets the value of a particular parameter for this debit transaction.
boolean	setupTransactionData(SHAiButtonUser user) Setup account data on a fresh user iButton.
boolean	verifyTransactionData(SHAiButtonUser user) Verifies user's account data.
boolean	verifyUser(SHAiButtonUser user) Verifies user's authentication response.

Methods inherited from class com.dalsemi.onewire.application.sha.SHATransaction

getLastCoprError, getLastError

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBIT_AMOUNT

public static final int DEBIT_AMOUNT

Update the amount this transaction will debit

INITIAL_AMOUNT

public static final int INITIAL_AMOUNT

Update the amount for initial account balance

USER_BALANCE

public static final int USER_BALANCE

Retrieve the amount for user's current balance

Constructor Detail

SHADebitUnsigned

public SHADebitUnsigned(SHAiButtonCopr copr)

SHADebitUnsigned constructor. copr is the SHAiButtonCopr that is used to perform this transaction. After saving a reference to the SHA coprocessor, this constructor resets all parameters for this type of transaction to their default values.

Parameters:

copr - The coprocessor used for authentication and data signing in this transaction.

SHADebitUnsigned

public SHADebitUnsigned(SHAiButtonCopr copr,
                        int initialAmount,
                        int debitAmount)

SHADebitUnsigned constructor. copr is the SHAiButtonCopr that is used to perform this transaction. After saving a reference to the SHA coprocessor, this constructor resets all parameters for this type of transaction to their default values.

Parameters:

copr - The coprocessor used for authentication and data signing in this transaction.

Method Detail

setupTransactionData

public boolean setupTransactionData(SHAiButtonUser user)
                             throws OneWireException,
                                    OneWireIOException

Setup account data on a fresh user iButton. Prior to calling setup transaction data, the authentication secret for the iButton should already be setup and a directory entry (as well as at least an empty placeholder file) should exist for the account data. If you constructed the SHAiButtonUser using SHAiButtonUser(SHAiButtonCopr,OneWireContainer18,boolean,byte[]) the secret has been setup for you and you should know call this function. If you try to install the authentication secret after creating the account data, you will destroy all account data on the iButton.

You can set the value of the intial account balance by calling transaction.setParameter(SHADebit.INITIAL_AMOUNT,10000) where the value of the units is in cents (i.e. 10000 = $100).

Flow of action:

• Generate generic account page
• Insert the initial balance into account data
• Insert the (constant) digital signature
• Write account data page to iButton

Overrides:

setupTransactionData in class SHATransaction

Parameters:

user - SHAiButtonUser upon which the transaction occurs.

Returns:

trueif and only if the signature is successfully created by the coprocessor AND the data is successfully written to the user iButton.

See Also:

SHAiButtonUser.writeAccountData(byte[],int), SHATransaction.getLastError()

verifyUser

public boolean verifyUser(SHAiButtonUser user)
                   throws OneWireException,
                          OneWireIOException

Verifies user's authentication response. User is "authenticated" if and only if the digital signature generated the user iButton matches the digital signature generated by the coprocessor after the user's unique secret has been recreated on the coprocessor.

Flow of action:

• Generate 3-byte "challenge" on coprocessor
• Write challenge to scratchpad of user
• Read account data page with signature
• Attempt to match user's signature with the coprocessor

Overrides:

verifyUser in class SHATransaction

Parameters:

user - SHAiButtonUser upon which the transaction occurs.

See Also:

SHAiButtonCopr.generateChallenge(int,byte[],int), SHAiButtonCopr.verifyAuthentication(byte[],byte[],byte[],byte[],byte), SHAiButtonUser.readAccountData(byte[],int,byte[],int,byte[],int), SHATransaction.getLastError()

verifyTransactionData

public boolean verifyTransactionData(SHAiButtonUser user)
                              throws OneWireException,
                                     OneWireIOException

Verifies user's account data. Account data is "verified" if and only if the account balance is greater than zero. No digital signature is checked by this transaction.

Flow of action:

• Read the account data from user
• Extract account balance
• Debit money from balance
• Insert the new balance
• Write the account data to the user

If previous steps have been executed, all "Read" commands on the user are reading from cached data.

Overrides:

verifyTransactionData in class SHATransaction

Parameters:

user - SHAiButtonUser upon which the transaction occurs.

Returns:

true if and only if the account balance is greater than zero.

See Also:

SHAiButtonUser.readAccountData(byte[],int), SHATransaction.getLastError()

executeTransaction

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

Performs the unsigned debit, subtracting the debit amount from the user's balance and storing the new, unsigned account data on the user's iButton. The debit amount can be set using transaction.setParameter(SHADebit.DEBIT_AMOUNT, 50), where the value is in units of cents (i.e. for 1 dollar, use 100).

Flow of action:

• Read the account data from user
• Extract account balance
• Assert balance greater than debit amount
• Debit money from balance
• Insert the new balance
• Write the account data to the user

If previous steps have been executed, all "Read" commands on the user are reading from cached data.

Overrides:

executeTransaction in class SHATransaction

Parameters:

user - SHAiButtonUser upon which the transaction occurs.

Returns:

true if and only if the user has enough in the account balance to perform the requested debit AND the account data has been written to the button.

See Also:

SHAiButtonUser.readAccountData(byte[],int), SHAiButtonUser.writeAccountData(byte[],int), SHATransaction.getLastError()

getParameter

public int getParameter(int type)

Retrieves the value of a particular parameter for this debit transaction.

Valid Parameters

• SHADebit.DEBIT_AMOUNT
• SHADebit.INITIAL_AMOUNT
• SHADebit.USER_BALANCE

Note that the value of SHADebit.USER_BALANCE will be set after calling verifyTransactionData(SHAiButtonUser) and after calling executeTransaction(SHAiButtonUser).

Overrides:

getParameter in class SHATransaction

Returns:

The value of the requested parameter.

Throws:

IllegalArgumentException - if an invalid parameter type is requested.

setParameter

public boolean setParameter(int type,
                            int param)

Sets the value of a particular parameter for this debit transaction.

Valid Parameters

• SHADebit.DEBIT_AMOUNT
• SHADebit.INITIAL_AMOUNT

Overrides:

setParameter in class SHATransaction

Parameters:

type - Specifies the parameter type (SHADebit.DEBIT_AMOUNT or SHADebit.INITIAL_AMOUNT)

Returns:

true if a valid parameter type was specified and the value of the parameter is positive.

Throws:

IllegalArgumentException - if an invalid parameter type is requested.

resetParameters

public void resetParameters()

Resets all transaction parameters to default values

Overrides:

resetParameters in class SHATransaction