Class SHAiButtonUser33
Class representing DS1961S (or DS2432), family-code 0x33, SHA iButtons as a user token in SHA Transactions.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected SHAiButtonCopr
Must maintain a reference to the coprocessor for generating the COPY_SCRATCHPAD authentication.protected OneWireContainer33
Reference to the OneWireContainerFields inherited from class com.dalsemi.onewire.application.sha.SHAiButtonUser
accountData, accountPageNumber, address, forceOverdrive, fullBindCode, serviceFile, strServiceFilename, writeCycleCounter
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
No default constructor for user apps.SHAiButtonUser33
(byte[] coprBindCode, byte[] fileName, int fileNameExt, OneWireContainer33 owc) Creates a valid SHAiButtonUser object.SHAiButtonUser33
(byte[] coprBindCode, byte[] fileName, int fileNameExt, OneWireContainer33 owc, boolean formatDevice, byte[] authSecret) Initialize a DS1961S as a fresh user iButton for a given SHA service.SHAiButtonUser33
(SHAiButtonCopr copr, SHAiButtonCopr authCopr) Creates a mostly uninitialized SHAiButtonUser object.SHAiButtonUser33
(SHAiButtonCopr copr, SHAiButtonCopr authCopr, OneWireContainer33 owc) Creates a valid SHAiButtonUser object.SHAiButtonUser33
(SHAiButtonCopr copr, OneWireContainer33 owc, boolean formatDevice, byte[] authSecret) Initialize a DS1961S as a fresh user iButton for a given SHA service. -
Method Summary
Modifier and TypeMethodDescriptionbyte
Returns a byte representing the appropriate authorization command for the coprocessor to use to authenticate this user.void
getFullBindCode
(byte[] l_fullBindCode, int offset) 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.int
Returns the value of the write cycle counter for the page where the account data is stored.boolean
Returnstrue
if this buttons account data is stored on a page that has a write cycle counter.boolean
readAccountData
(byte[] dataBuffer, int offset) Reads the account data off the SHAiButton using a standard READ command.int
readAccountData
(byte[] chlg, int chlgStart, byte[] dataBuffer, int dataStart, byte[] mac, int macStart) Reads the account data off the SHAiButton using a READ_AUTHENTICATE command.boolean
Refreshes eeprom SHA devices in case of weakly-programmed bits on the account page.boolean
Modifies this SHA iButton so that it refers to another DS1961S container.boolean
setiButtonUser
(byte[] address) Modifies this SHA iButton so that it refers to another device.boolean
setiButtonUser
(DSPortAdapter adapter, byte[] address) Modifies this SHA iButton so that it refers to another 1963S.boolean
writeAccountData
(byte[] dataBuffer, int offset) Writes the account data to the SHAiButton.Methods inherited from class com.dalsemi.onewire.application.sha.SHAiButtonUser
checkAccountPageInfo, createServiceFile, getAccountFilename, getAccountPageNumber, getAddress, getAddress, getAddress, getForceOverdrive, setForceOverdrive, toString
-
Field Details
-
ibc33
Reference to the OneWireContainer -
copr
Must maintain a reference to the coprocessor for generating the COPY_SCRATCHPAD authentication. This is what is referred to as the write-authorization coprocessor.
-
-
Constructor Details
-
SHAiButtonUser33
protected SHAiButtonUser33()No default constructor for user apps. At bare minimum, you need a reference to a
SHAiButtonCopr
for the transaction system and aSHAiButtonCopr
for generating the DS1961S write authorization for the copy-scratchpad command.Note: These can be the same coprocessor if you're transaction system is using unsigned transaction data.
-
SHAiButtonUser33
public SHAiButtonUser33(SHAiButtonCopr copr, OneWireContainer33 owc, boolean formatDevice, byte[] authSecret) throws OneWireException, OneWireIOException Initialize a DS1961S 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.
Note: With this constructor, the master secret is installed and bound to the iButton, so the final secret is none by the object. For that reason, a hardware coprocessor is not necessary for generating the write-authorization MAC.
- 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
- Iftrue
, the TMEX filesystem will be formatted before the account service file is created.authSecret
- The master authentication secret for the system.- Throws:
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:
-
SHAiButtonUser33
public SHAiButtonUser33(byte[] coprBindCode, byte[] fileName, int fileNameExt, OneWireContainer33 owc, boolean formatDevice, byte[] authSecret) throws OneWireException, OneWireIOException Initialize a DS1961S 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.
Note: With this constructor, the master secret is installed and bound to the iButton, so the final secret is none by the object. For that reason, a hardware coprocessor is not necessary for generating the write-authorization MAC.
- Parameters:
coprBindCode
- The Coprocessor Bind Code without the information.fileName
- The file name from the Coprocessor.fileNameExt
- The file extension from the Coprocessorowc
- The DS1963S iButton that this object will refer to.formatDevice
- Iftrue
, the TMEX filesystem will be formatted before the account service file is created.authSecret
- The master authentication secret for the system.- Throws:
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:
-
SHAiButtonUser33
public SHAiButtonUser33(SHAiButtonCopr copr, SHAiButtonCopr authCopr, OneWireContainer33 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".Note: The same coprocessor can be used for write-authorization as authentication if you're transaction system is using unsigned transaction data.
- 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.authCopr
- The SHAiButtonCopr used to generate the write-authorization MAC for the copy-scratchpad command of the DS1961S.owc
- The DS1961S iButton that this object will refer to.- Throws:
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:
-
SHAiButtonUser33
public SHAiButtonUser33(byte[] coprBindCode, byte[] fileName, int fileNameExt, OneWireContainer33 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".Note: The same coprocessor can be used for write-authorization as authentication if you're transaction system is using unsigned transaction data.
- Parameters:
coprBindCode
- The Coprocessor Bind Code without the information.fileName
- The file name from the Coprocessor.fileNameExt
- The file extension from the CoprocessorauthCopr
- The SHAiButtonCopr used to generate the write-authorization MAC for the copy-scratchpad command of the DS1961S.owc
- The DS1961S iButton that this object will refer to.- Throws:
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:
-
SHAiButtonUser33
Creates a mostly uninitialized 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 uninitialized, 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.Note: The same coprocessor can be used for write-authorization as authentication if you're transaction system is using unsigned transaction data.
- 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.authCopr
- The SHAiButtonCopr used to generate the write-authorization MAC for the copy-scratchpad command of the DS1961S.- See Also:
-
-
Method Details
-
setiButton33
Modifies this SHA iButton so that it refers to another DS1961S 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 account info file associated with the system.
- Parameters:
owc
- TheOneWireContainer33
this object will refer to.- Returns:
true
if a valid account service file exists on thisOneWireContainer33
.- Throws:
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
-
setiButtonUser
public boolean setiButtonUser(DSPortAdapter adapter, byte[] address) throws OneWireException, OneWireIOException 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.
- Specified by:
setiButtonUser
in classSHAiButtonUser
- 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 thisOneWireContainer18
.- Throws:
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
-
setiButtonUser
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.
- Specified by:
setiButtonUser
in classSHAiButtonUser
- Parameters:
address
- The address of the 1-Wire device- Returns:
true
if a valid account service file exists on thisOneWireContainer18
.- Throws:
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
-
getWriteCycleCounter
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.
Since the DS1961S has no "write cycle counters", this function always returns -1.
- Specified by:
getWriteCycleCounter
in classSHAiButtonUser
- Returns:
- the value of the write cycle counter for the account data page.
- Throws:
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
-
hasWriteCycleCounter
public boolean hasWriteCycleCounter()Returns
true
if this buttons account data is stored on a page that has a write cycle counter.Since the DS1961S has no "write cycle counters", this function always returns false.
- Specified by:
hasWriteCycleCounter
in classSHAiButtonUser
- Returns:
true
if account page has write cycle counter.
-
getFullBindCode
public void getFullBindCode(byte[] l_fullBindCode, int offset) 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:
( 0x0000FF ), ( 0x0000FF ), ( 0x0000FF ), ( 0x0000FF ), (svcPageNum), (deviceAN+0), (deviceAN+1), (deviceAN+2), (deviceAN+3), (deviceAN+4), (deviceAN+5), (deviceAN+6), ( 0x0000FF ), ( 0x0000FF ), ( 0x0000FF )
- Specified by:
getFullBindCode
in classSHAiButtonUser
- Parameters:
bindCode
- the 7-byte binding code from coprocessor's service filefullBindCode
- 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.
-
getAuthorizationCommand
public byte getAuthorizationCommand()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.
- Specified by:
getAuthorizationCommand
in classSHAiButtonUser
- Returns:
- byte indicating appropriate command for authenticating user
-
writeAccountData
public boolean writeAccountData(byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException 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.
Note that for the DS1961S user button, an authorization MAC must be generated for the copy-scratchpad command. Since the scratchpad is only 8 bytes long, this must be done 4 times to write a page of data. So, this function only writes (in 8 byte blocks) the bytes that have changed.
- Specified by:
writeAccountData
in classSHAiButtonUser
- Parameters:
dataBuffer
- the buffer to copy the account data fromoffset
- the index into the buffer where copying should begin- Returns:
- whether or not the data write succeeded
- Throws:
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
-
readAccountData
public boolean readAccountData(byte[] dataBuffer, int offset) throws OneWireException, OneWireIOException 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.
- Specified by:
readAccountData
in classSHAiButtonUser
- Parameters:
dataBuffer
- the buffer to copy the account data intooffset
- the index into the buffer where copying should begin- Returns:
- whether or not the read was successful
- Throws:
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
-
readAccountData
public int readAccountData(byte[] chlg, int chlgStart, byte[] dataBuffer, int dataStart, byte[] mac, int macStart) throws OneWireException, OneWireIOException 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
- Specified by:
readAccountData
in classSHAiButtonUser
- 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 intodataStart
- the index into the buffer where copying should beginmac
- the buffer to copy the resulting Message Authentication CodemacStart
- the index into the mac buffer to start copying- Returns:
- the value of the write cycle counter for the page
- Throws:
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
-
refreshDevice
Refreshes eeprom SHA devices in case of weakly-programmed bits on the account page.- Overrides:
refreshDevice
in classSHAiButtonUser
- Returns:
- true if the refresh was successful
- Throws:
OneWireException
OneWireIOException
-