Class SHASoftAuth


  • public class SHASoftAuth
    extends SHATransaction

    This class implements an software authrization account application for SHA Transactions. The account data is stored on the user iButtons after being digitally signed by a virtual machine coprocessor. 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
     byte[] ver_data = new byte[] { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06 };
     SATransaction trans = new SHAsoftauth(copr, ver_data, 7);
     
     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
            if (trans.verifyTransactionData(user)) {
                    System.out.println("Account Data Verified Successfully");
     
                    // writes verification data to user iButton
                    System.out.println("User's verification data: ");
                    softauth.getParameter(SHASoftAuth.VERIFICATION_DATA, ver_data, 0, 7);
                    IOHelper.writeBytes(ver_data);
            }
     }
     
     // ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
     
     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.

    See Also:
    SHATransaction, SHAiButtonCopr, SHAiButtonUser
    • Constructor Detail

      • SHASoftAuth

        protected SHASoftAuth()
        User apps should never call this
      • SHASoftAuth

        public SHASoftAuth​(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.
      • SHASoftAuth

        public SHASoftAuth​(SHAiButtonCopr copr,
                           byte[] extra_data,
                           int len)
        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.
        extra_data - The 7 bytes of extra data to be used instead of the balance.
        len - The len, 7 or less of the data. It is 0 padded.
    • 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 initial 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

        Specified by:
        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.
        Throws:
        OneWireException
        OneWireIOException
        See Also:
        SHAiButtonCopr.createDataSignature(byte[],byte[],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).

        Specified by:
        getParameter in class SHATransaction
        Returns:
        The value of the requested parameter.
        Throws:
        java.lang.IllegalArgumentException - if an invalid parameter type is requested.
      • getParameter

        public int getParameter​(int type,
                                byte[] data,
                                int offset,
                                int len)

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

        Returns:
        The value of the requested parameter.
        Throws:
        java.lang.IllegalArgumentException - if an invalid parameter type is requested.
      • setParameter

        public boolean setParameter​(int type,
                                    byte[] data,
                                    int offset,
                                    int len)

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

        Valid Parameters

        • SHADebit.DEBIT_AMOUNT
        • SHADebit.INITIAL_AMOUNT

        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:
        java.lang.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

        Specified by:
        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:
        java.lang.IllegalArgumentException - if an invalid parameter type is requested.
      • resetParameters

        public void resetParameters()

        Resets all transaction parameters to default values

        Specified by:
        resetParameters in class SHATransaction