SHAiButtonUser18 Class Reference

Inherits com::dalsemi::onewire::application::sha::SHAiButtonUser.

List of all members.


Detailed Description

Class representing DS1963S (or DS2421), family-code 0x18, SHA iButtons as a user token in SHA Transactions.

See also:
SHATransaction

SHAiButtonCopr

SHAiButtonUser33

Version:
1.00
Author:
SKH

Public Member Functions

 SHAiButtonUser18 (SHAiButtonCopr copr, OneWireContainer18 owc, boolean formatDevice, byte[] authSecret) throws OneWireException, OneWireIOException
 SHAiButtonUser18 (byte[] coprBindData, byte[] coprBindCode, byte[] fileName, int fileNameExt, OneWireContainer18 owc, boolean formatDevice, byte[] authSecret) throws OneWireException, OneWireIOException
 SHAiButtonUser18 (SHAiButtonCopr copr, OneWireContainer18 owc) throws OneWireException, OneWireIOException
 SHAiButtonUser18 (byte[] coprBindCode, byte[] fileName, int fileNameExt, OneWireContainer18 owc) throws OneWireException, OneWireIOException
 SHAiButtonUser18 (SHAiButtonCopr copr)
synchronized boolean setiButton18 (OneWireContainer18 owc) throws OneWireException, OneWireIOException
synchronized boolean setiButtonUser (DSPortAdapter adapter, byte[] address) throws OneWireException, OneWireIOException
synchronized boolean setiButtonUser (byte[] address) throws OneWireException, OneWireIOException
synchronized int getWriteCycleCounter () throws OneWireException, OneWireIOException
synchronized boolean hasWriteCycleCounter ()
 Returns true if this buttons account data is stored on a page that has a write cycle counter.
void getFullBindCode (byte[] l_fullBindCode, int offset)
byte getAuthorizationCommand ()
synchronized boolean writeAccountData (byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException
synchronized boolean readAccountData (byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException
synchronized int readAccountData (byte[] chlg, int chlgStart, byte[] dataBuffer, int dataStart, byte[] mac, int macStart) throws OneWireException, OneWireIOException

Protected Member Functions

 SHAiButtonUser18 ()

Protected Attributes

OneWireContainer18 ibc = null
 Reference to the OneWireContainer.

Constructor & Destructor Documentation

SHAiButtonUser18 (  )  [protected]

No default constructor for user apps. At bare minimum, you need a reference to a SHAiButtonCopr before you can construct a SHAiButtonUser.

See also:
SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18,boolean,byte[])

SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18)

SHAiButtonUser18(SHAiButtonCopr)

SHAiButtonUser18 ( SHAiButtonCopr  copr,
OneWireContainer18  owc,
boolean  formatDevice,
byte[]  authSecret 
) throws OneWireException, OneWireIOException

Initialize a DS1963S as a fresh user iButton for a given SHA service. This constructor not only creates the service file for the user iButton using the TMEX file structure, but it also installs the master authentication secret and binds it to the iButton (making it unique for a particular button). Optionally, the device can be formatted before the service file is installed.

Parameters:
copr The SHAiButtonCopr to which the user object is tied. This Coprocessor contains the necessary binding code and service filename, necessary for both locating a user and recreating his unique secret.
owc The DS1963S iButton that this object will refer to.
formatDevice If true, the TMEX filesystem will be formatted before the account service file is created.
authSecret The master authentication secret for the systm.
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
See also:
SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18)

SHAiButtonUser18(SHAiButtonCopr)

SHAiButtonUser18 ( byte[]  coprBindData,
byte[]  coprBindCode,
byte[]  fileName,
int  fileNameExt,
OneWireContainer18  owc,
boolean  formatDevice,
byte[]  authSecret 
) throws OneWireException, OneWireIOException

Initialize a DS1963S as a fresh user iButton for a given SHA service. This constructor not only creates the service file for the user iButton using the TMEX file structure, but it also installs the master authentication secret and binds it to the iButton (making it unique for a particular button). Optionally, the device can be formatted before the service file is installed.

Parameters:
coprBindData The Coprocessor Bind Data, used to create a unique secret for this user token.
coprBindCode The Coprocessor Bind Code without the user-specific information, used to create a unique secret for this user token.
fileName The file name for the account info.
fileNameExt The file extenstion for the account info
owc The DS1963S iButton that this object will refer to.
formatDevice If true, the TMEX filesystem will be formatted before the account service file is created.
authSecret The master authentication secret for the systm.
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
See also:
SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18)

SHAiButtonUser18(SHAiButtonCopr)

Creates a valid SHAiButtonUser object. If the service file, whose name is taken from the SHAiButtonCopr, is not found on the user iButton, a OneWireException is thrown with the message "Invalid SHA user".

Parameters:
copr The SHAiButtonCopr to which the user object is tied. This Coprocessor contains the necessary binding code and service filename, necessary for both locating a user and recreating his unique secret.
owc The DS1963S iButton that this object will refer to.
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
See also:
SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18,boolean,byte[])

SHAiButtonUser18(SHAiButtonCopr)

SHAiButtonUser18 ( byte[]  coprBindCode,
byte[]  fileName,
int  fileNameExt,
OneWireContainer18  owc 
) throws OneWireException, OneWireIOException

Creates a valid SHAiButtonUser object. If the service file, whose name is taken from the SHAiButtonCopr, is not found on the user iButton, a OneWireException is thrown with the message "Invalid SHA user".

Parameters:
coprBindCode The Coprocessor Bind Code without the user-specific information.
fileName The file name of the account file
fileNameExt The file extenstion of the account file
owc The DS1963S iButton that this object will refer to.
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
See also:
SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18,boolean,byte[])

SHAiButtonUser18(SHAiButtonCopr)

Creates a mostly unitialized SHAiButtonUser object. This constructor merely copies the coprocessors 7 byte binding code into a local cache and stores the name of the account service file used for all user iButtons.

Since this constructor leaves data unitialized, you should be very careful with the use of it. It is expected that after calling this constructor, the user will call setiButton to finish the initialization process. On memory-starved platforms, this should help optimize memory usage.

Parameters:
copr The SHAiButtonCopr to which the user object is tied. This Coprocessor contains the necessary binding code and service filename, necessary for both locating a user and recreating his unique secret.
See also:
SHAiButtonUser18(SHAiButtonCopr,OneWireContainer18,boolean,byte[])

SHAiButtonUser18(SHAiButtonCopr)


Member Function Documentation

synchronized boolean setiButton18 ( OneWireContainer18  owc  )  throws OneWireException, OneWireIOException

Modifies this SHA iButton so that it refers to another DS1963S container. This function only copies the reference to the OneWireContainer, copes the reference to it's 1-Wire address, and then asserts that the iButton contains a valid acccount info file associated with the system.

Parameters:
owc The OneWireContainer18 this object will refer to.
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

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

Modifies this SHA iButton so that it refers to another 1963S. 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

Implements SHAiButtonUser.

synchronized boolean setiButtonUser ( byte[]  address  )  throws OneWireException, OneWireIOException [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

Implements SHAiButtonUser.

synchronized int getWriteCycleCounter (  )  throws OneWireException, OneWireIOException [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.

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

Implements SHAiButtonUser.

synchronized boolean hasWriteCycleCounter (  )  [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.

Implements SHAiButtonUser.

void getFullBindCode ( byte[]  l_fullBindCode,
int  offset 
) [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.

For the DS1963S user iButton, the format of the full bind code is as follows:

      (bindCode+0), (bindCode+1), (bindCode+2), (bindCode+3),
      (svcPageNum), (deviceAN+0), (deviceAN+1), (deviceAN+2),
      (deviceAN+3), (deviceAN+4), (deviceAN+5), (deviceAN+6),
      (bindCode+4), (bindCode+5), (bindCode+6)
   

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.

Implements SHAiButtonUser.

byte getAuthorizationCommand (  )  [virtual]

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

Returns:
byte indicating appropriate command for authenticating user

Implements SHAiButtonUser.

synchronized boolean writeAccountData ( byte[]  dataBuffer,
int  offset 
) throws OneWireException, OneWireIOException [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

Implements SHAiButtonUser.

synchronized boolean readAccountData ( byte[]  dataBuffer,
int  offset 
) throws OneWireException, OneWireIOException [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

Implements SHAiButtonUser.

synchronized int readAccountData ( byte[]  chlg,
int  chlgStart,
byte[]  dataBuffer,
int  dataStart,
byte[]  mac,
int  macStart 
) throws OneWireException, OneWireIOException [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

Implements SHAiButtonUser.


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