SHAiButtonUser Class Reference

Inherited by SHAiButtonUser18, and SHAiButtonUser33.

List of all members.


Detailed Description

The abstract superclass for all users of a SHAiButton transaction system. The user in a SHA transaction system mainly consists of a page (or pages) of account data. The abstract superclass guarantees an interface for retrieving information about account data, as well as reading and writing that data.

SHAiButtonUser was defined for use with the DS1963S (family code 0x18) and the DS1961S (family code 0x33). The benefit to using our SHA iButtons in a transaction is for device authentication. Using a challenge-response protocol, the DS1961S and the DS1963S can authenticate themselves to the system before their actual account data is verified. But, if device authentication isn't important to your transaction, the SHAiButtonUser can be extended to support any 1-Wire memory device.

The format of user's account data is not specified by this class, only the interface for accessing it. Each different SHATransaction is free to implement whatever format is appropriate for the transaction type.

See also:
SHATransaction

SHAiButtonCopr

SHAiButtonUser18

SHAiButtonUser33

Version:
1.00
Author:
SKH

Public Member Functions

int getAccountPageNumber ()
String getAccountFilename ()
byte[] getAddress ()
void getAddress (byte[] data, int offset)
void getAddress (byte[] data, int offset, int cnt)
void setForceOverdrive (boolean value)
 Sets whether or not the container should be forced into overdrive.
boolean getForceOverdrive ()
 Reports whether or not the container is forced into overdrive.
abstract boolean setiButtonUser (DSPortAdapter adapter, byte[] address) throws OneWireException, OneWireIOException
abstract boolean setiButtonUser (byte[] address) throws OneWireException, OneWireIOException
abstract int getWriteCycleCounter () throws OneWireException, OneWireIOException
abstract boolean hasWriteCycleCounter ()
abstract void getFullBindCode (byte[] l_fullBindCode, int offset)
abstract byte getAuthorizationCommand ()
abstract boolean writeAccountData (byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException
abstract boolean readAccountData (byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException
abstract int readAccountData (byte[] chlg, int chlgStart, byte[] dataBuffer, int dataStart, byte[] mac, int macStart) throws OneWireException, OneWireIOException
boolean refreshDevice () throws OneWireException,OneWireIOException
 Refreshes eeprom SHA devices in case of weakly-programmed bits on the account page.
String toString ()

Protected Member Functions

boolean createServiceFile (OneWireContainer owc, String filename, boolean formatDevice)
synchronized boolean checkAccountPageInfo (OneWireContainer ibc)

Protected Attributes

byte[] address = null
 Cache of 1-Wire Address.
final byte[] accountData = new byte[32]
 local cache of accountData
int accountPageNumber = -1
 page number account data is stored on
final byte[] serviceFile
 used to construct appropriate string for OWFile constructor
String strServiceFilename = null
 stores string name of user's service file
final byte[] fullBindCode = new byte[15]
 maintains a cache of the fullBindCode, for later binding of coprocessor.
int writeCycleCounter = -1
 local cache of writeCycleCounter for data page
boolean forceOverdrive = false
 force 1-wire container into overdrive speed

Static Package Attributes

static final boolean DEBUG = false
 Turns on extra debugging output.

Member Function Documentation

int getAccountPageNumber (  ) 

Returns the page number of the first memory page where account data is stored.

Returns:
page number where account data is stored.

String getAccountFilename (  ) 

Returns the TMEX filename of the user's account data file.

Returns:
filename of user's account data file

byte [] getAddress (  ) 

Returns the 8 byte address of the OneWireContainer this SHAiButton refers to.

Returns:
8 byte array containing family code, address, and crc8 of the OneWire device.

void getAddress ( byte[]  data,
int  offset 
)

Copies the 8 byte address of the OneWireContainer into the provided array starting at the given offset.

Parameters:
data array with at least 8 bytes after offset
offset the index at which copying starts

void getAddress ( byte[]  data,
int  offset,
int  cnt 
)

Copies the specified number of bytes from the address of the OneWireContainer into the provided array starting at the given offset.

Parameters:
data array with at least cnt bytes after offset
offset the index at which copying starts
cnt the number of bytes to copy

void setForceOverdrive ( boolean  value  ) 

Sets whether or not the container should be forced into overdrive.

Parameters:
value if true, the container will be forced to overdrive

boolean getForceOverdrive (  ) 

Reports whether or not the container is forced into overdrive.

Returns:
if true, the container will be forced to overdrive

boolean createServiceFile ( OneWireContainer  owc,
String  filename,
boolean  formatDevice 
) [protected]

Create's empty service file for the user with the given filename. Also, it populates accountPageNumber with the page that the service file is stored on.

Parameters:
owc the 1-wire device where the service file will be created.
filename the filename of the service file.
formatDevice if true, the device is formatted before creating the service file.

synchronized boolean checkAccountPageInfo ( OneWireContainer  ibc  )  [protected]

Asserts that proper account info exists for this SHAiButtonUser and establishes a buffer for caching account data.

Parameters:
ibc the OneWireContainer whose account info is checked
Returns:
whether or not the device is initialized properly

abstract boolean setiButtonUser ( DSPortAdapter  adapter,
byte[]  address 
) throws OneWireException, OneWireIOException [pure virtual]

Modifies this SHA iButton so that it refers to another device. If this object already has an appropriate instance of OneWireContainer, that instance is updated with the new address.

Parameters:
adapter The adapter that the device can be found on.
address The address of the 1-Wire device
Returns:
true if a valid account service file exists on this OneWireContainer18.
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract boolean setiButtonUser ( byte[]  address  )  throws OneWireException, OneWireIOException [pure virtual]

Modifies this SHA iButton so that it refers to another device. If this object does not already has an appropriate instance of OneWireContainer, it returns false immediately, because there is no adapter info available. Otherwise, it reuses the same adapter.

Parameters:
address The address of the 1-Wire device
Returns:
true if a valid account service file exists on this OneWireContainer18.
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract int getWriteCycleCounter (  )  throws OneWireException, OneWireIOException [pure virtual]

Returns the value of the write cycle counter for the page where the account data is stored. If the write cycle counter has ever been retrieved, this returns the cached value. Otherwise, this method reads the value from the part.

For devices that do not support write cycle counters, this method always returns -1.

Returns:
the value of the write cycle counter for the account data page.
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract boolean hasWriteCycleCounter (  )  [pure virtual]

Returns true if this buttons account data is stored on a page that has a write cycle counter.

Returns:
true if account page has write cycle counter.

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract void getFullBindCode ( byte[]  l_fullBindCode,
int  offset 
) [pure virtual]

This function creates the full 15-byte binding data for the coprocessor to use to recreate this user's secret on the copr's workspace page. This function is located in the SHAiButtonUser class to support binding codes for user buttons who use alternate techniques (such as the DS1961S) for secret computation.

Parameters:
bindCode the 7-byte binding code from coprocessor's service file
fullBindCode the 15-byte full binding code to to be copied into the coprocessor's scratchpad. There should be 15 bytes available starting from the offset.
offset the offset into fullBindCode where copying should begin.

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract byte getAuthorizationCommand (  )  [pure virtual]

Returns a byte representing the appropriate authorization command for the coprocessor to use to authenticate this user. For a DS1961S, the authentication command is AUTH_HOST, but for a DS1963S, the authentication command is VALIDATE_PAGE.

Returns:
byte indicating appropriate command for authenticating user

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract boolean writeAccountData ( byte[]  dataBuffer,
int  offset 
) throws OneWireException, OneWireIOException [pure virtual]

Writes the account data to the SHAiButton. First, this function asserts that the account page number is known. The account data is copied from dataBuffer starting at the offset. If there are less than 32 bytes available to copy, this function only copies the bytes that are available.

Parameters:
dataBuffer the buffer to copy the account data from
offset the index into the buffer where copying should begin
Returns:
whether or not the data write succeeded
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract boolean readAccountData ( byte[]  dataBuffer,
int  offset 
) throws OneWireException, OneWireIOException [pure virtual]

Reads the account data off the SHAiButton using a standard READ command. First, this function asserts that the account page number is known as well as the length of the account file. The 32 byte account data page is copied into dataBuffer starting at the given offset.

Parameters:
dataBuffer the buffer to copy the account data into
offset the index into the buffer where copying should begin
Returns:
whether or not the read was successful
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

abstract int readAccountData ( byte[]  chlg,
int  chlgStart,
byte[]  dataBuffer,
int  dataStart,
byte[]  mac,
int  macStart 
) throws OneWireException, OneWireIOException [pure virtual]

Reads the account data off the SHAiButton using a READ_AUTHENTICATE command. First, this function asserts that the account page number is known as well as the length of the account file. Then it copies the 3 byte challenge to the scratchpad before sending the command for READ_AUTHENTICATE. The 32 byte account data page is copied into dataBuffer starting at dataStart.

In addition to the account data, this function also returns a calculated MAC. The MAC requires 20 bytes after the start index. The return value is the write cycle counter value for the account data page

Parameters:
chlg the buffer containing a 3-byte random challenge.
chlgStart the index into the buffer where the 3 byte challenge begins.
dataBuffer the buffer to copy the account data into
dataStart the index into the buffer where copying should begin
mac the buffer to copy the resulting Message Authentication Code
macStart the index into the mac buffer to start copying
Returns:
the value of the write cycle counter for the page
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

Implemented in SHAiButtonUser18, and SHAiButtonUser33.

boolean refreshDevice (  )  throws OneWireException,OneWireIOException

Refreshes eeprom SHA devices in case of weakly-programmed bits on the account page.

Returns:
true if the refresh was successful

Reimplemented in SHAiButtonUser33.

String toString (  ) 

Returns a string representing this SHAiButton.

Returns:
a string containing the 8-byte address of this 1-Wire device.


The documentation for this class was generated from the following file:

Generated on Thu Aug 28 15:42:31 2008 for 1-Wire API for .NET by  doxygen 1.5.6