Dallas Semiconductor 1-Wire API 1.00 Alpha: Class SHADebit

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 SHADebit

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

public class SHADebit
extends SHATransaction

This class implements an account debit application for SHA Transactions. Account data is stored on user iButtons after being digitally signed by a coprocessor iButton. 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
- 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 SHADebit(copr, 10000, 50);

       OneWireContainer18 owc18 = new OneWireContainer18(adapter, userAddress);

       //The following constructor erases all transaction data from the user and
       //installs the system authentication secret on the user iButton.
       SHAiButtonUser user = new SHAiButtonUser18(copr, owc18, 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");

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

       //"challenges" user iButton
       if(trans.verifyUser(user))
       {
          System.out.println("User Verified Successfully");

          //checks data signature and account balance>0
          if(trans.verifyTransactionData(user))
          {
             System.out.println("Account Data Verified Successfully");

             //debits and writes new data to user iButton
             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
`SHADebit(SHAiButtonCopr copr)` SHADebit constructor.
`SHADebit(SHAiButtonCopr copr, int initialAmount, int debitAmount)` SHADebit constructor.

Method Summary
`boolean` | `executeTransaction(SHAiButtonUser user, boolean verifySuccess)` Performs the signed debit, subtracting the debit amount from the user's balance and storing the new, signed 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

### SHADebit

    public SHADebit(SHAiButtonCopr copr)

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

### SHADebit

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

  SHADebit 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
  - Create a signature using coprocessor
  - Insert the digital signature
  - Write account data page to iButton
  Overrides:
    `setupTransactionData` in class `SHATransaction`
  Parameters:
    `user` - SHAiButtonUser upon which the transaction occurs.
  Returns:
    `true`if and only if the signature is successfully created by the coprocessor AND the data is successfully written to the user iButton.
  See Also:
    `SHAiButtonCopr.createDataSignature(byte[],byte[],byte[],int)`, `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 and the digital signature matches the signature recreated by the coprocessor.

  Flow of action:

  - Read the account data from user
  - Extract account balance
  - Debit money from balance
  - Insert the new balance
  - Reset the digital signature
  - Use coprocessor to sign account data
  - Insert the new digital signature
  - 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 and digital signature matches the signature recreated by the coprocessor.
  See Also:
    `SHAiButtonUser.readAccountData(byte[],int)`, `SHAiButtonCopr.verifySignature(byte[],byte[],byte[])`, `SHATransaction.getLastError()`

### executeTransaction

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

  Performs the signed debit, subtracting the debit amount from the user's balance and storing the new, signed 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
  - Reset the digital signature
  - Use coprocessor to sign account data
  - Insert the new digital signature
  - 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 a new digital signature is successfully created AND the account data has been written to the button.
  See Also:
    `SHAiButtonUser.readAccountData(byte[],int)`, `SHAiButtonUser.writeAccountData(byte[],int)`, `SHAiButtonCopr.createDataSignature(byte[],byte[],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`

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