Class SHASoftAuth
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:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final int
indices for fields in user account filestatic final int
static final int
static final int
Update the verification dataFields inherited from class com.dalsemi.onewire.application.sha.SHATransaction
copr, COPR_BIND_SECRET_FAILED, COPR_COMPUTE_CHALLENGE_FAILED, COPR_WRITE_DATAPAGE_FAILED, COPR_WRITE_SCRATCHPAD_FAILED, COPROCESSOR_FAILURE, lastError, 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
ModifierConstructorDescriptionprotected
User apps should never call thisSHASoftAuth
(SHAiButtonCopr copr) SHADebit constructor.SHASoftAuth
(SHAiButtonCopr copr, byte[] extra_data, int len) SHADebit constructor. -
Method Summary
Modifier and TypeMethodDescriptionboolean
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.int
getParameter
(int type, byte[] data, int offset, int len) Retrieves the value of a particular parameter for this debit transaction.void
Resets all transaction parameters to default valuesboolean
setParameter
(int type, byte[] data, int offset, int len) Sets the value of a particular parameter for this debit transaction.boolean
setParameter
(int type, int param) Sets the value of a particular parameter for this debit transaction.boolean
Setup account data on a fresh user iButton.boolean
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
-
Field Details
-
VERIFICATION_DATA
public static final int VERIFICATION_DATAUpdate the verification data- See Also:
-
I_FILE_LENGTH
public static final int I_FILE_LENGTHindices for fields in user account file- See Also:
-
I_DATA_TYPE_CODE
public static final int I_DATA_TYPE_CODE- See Also:
-
I_SIGNATURE
public static final int I_SIGNATURE- See Also:
-
I_VERDATA
public static final int I_VERDATA- See Also:
-
I_CONTINUATION_PTR
public static final int I_CONTINUATION_PTR- See Also:
-
I_FILE_CRC16
public static final int I_FILE_CRC16- See Also:
-
-
Constructor Details
-
SHASoftAuth
protected SHASoftAuth()User apps should never call this -
SHASoftAuth
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
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 Details
-
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 classSHATransaction
- 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.- Throws:
OneWireException
OneWireIOException
- See Also:
-
verifyUser
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
- Specified by:
verifyUser
in classSHATransaction
- Parameters:
user
- SHAiButtonUser upon which the transaction occurs.- Throws:
OneWireException
OneWireIOException
- See Also:
-
verifyTransactionData
public boolean verifyTransactionData(SHAiButtonUser user) throws OneWireException, OneWireIOException Verifies user's account data. Account data is "verified" if the digital signature matches the signature recreated by the coprocessor.
Flow of action:
- Read the account data from user
- Get verification data
- 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.
- Specified by:
verifyTransactionData
in classSHATransaction
- 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.- Throws:
OneWireException
OneWireIOException
- See Also:
-
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
- 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.
- Specified by:
executeTransaction
in classSHATransaction
- Parameters:
user
- SHAiButtonUser upon which the transaction occurs.verifySuccess
- A boolean to let this method know if verification was successful.- 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.- Throws:
OneWireException
OneWireIOException
- See Also:
-
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 callingverifyTransactionData(SHAiButtonUser)
and after callingexecuteTransaction(SHAiButtonUser)
.- Specified by:
getParameter
in classSHATransaction
- Returns:
- The value of the requested parameter.
- Throws:
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 callingverifyTransactionData(SHAiButtonUser)
and after callingexecuteTransaction(SHAiButtonUser)
.- Returns:
- The value of the requested parameter.
- Throws:
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
orSHADebit.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.
-
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 classSHATransaction
- Parameters:
type
- Specifies the parameter type (SHADebit.DEBIT_AMOUNT
orSHADebit.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
- Specified by:
resetParameters
in classSHATransaction
-