1-Wire API for .NET Version 4.00
Public Member Functions | Protected Member Functions | Protected Attributes | Static Package Attributes

SHAiButtonCopr Class Reference

Inherited by SHAiButtonCoprVM.

List of all members.

Public Member Functions

 SHAiButtonCopr (OneWireContainer18 l_owc, String coprFilename, boolean l_formatDevice, int l_signPageNumber, int l_authPageNumber, int l_wspcPageNumber, int l_version, int l_encCode, byte l_serviceFileExt, byte[] l_serviceFilename, byte[] l_providerName, byte[] l_bindData, byte[] l_bindCode, byte[] l_auxData, byte[] l_initialSignature, byte[] l_signingChlg, byte[] l_signingSecret, byte[] l_authSecret) throws OneWireException, OneWireIOException
 SHAiButtonCopr (OneWireContainer18 owc, String coprFilename) throws OneWireException, OneWireIOException

Protected Member Functions

 SHAiButtonCopr ()

Protected Attributes

int lastError
 Last error code raised.
OneWireContainer18 ibc = null
 Reference to the OneWireContainer.
byte[] address = null
 Cache of 1-Wire Address.
int authPageNumber = -1
 Page used for generating user authentication secret.
String auxData
 Any auxilliary data stored on this coprocessor.
byte[] bindCode = new byte [7]
 7 bytes of binding data for scratchpad to bind secret installation
byte[] bindData = new byte [32]
 32 bytes of binding data to bind secret installation
boolean DS1961Scompatible = false
 Specifies whether or not this coprocessor is compatible with the DS1961S.
int encCode = -1
 Code used to specify encryption type.
byte[] filename = new byte[5]
 Filename, including extension, for user's service file.
byte[] initialSignature = new byte [20]
 20 byte initial signature, used for signing user account data
String providerName
 The Provider name of the coprocessor's service.
byte[] signingChallenge = new byte [3]
 3 byte challenge, used for signing user account data
int signPageNumber = 8
 Page used for signing user account data.
int version = -1
 Code used to specify encryption type.
int wspcPageNumber = -1
 Page used for generating user's validation MAC.

Static Package Attributes

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

Detailed Description

Class for holding instances of SHA iButton Coprocessors involved in SHA Transactions. The Coprocessor is used for digitally signing transaction data as well as generating random challenges for users and verifying their response.

A DS1963S SHA iButton can be a SHAiButtonCopr or a SHAiButtonUser. A Coprocessor iButton verifiessignatures and signs data for User iButtons. A Coprocessor might be located inside a vending machine, where a person would bring their User iButton. When the User iButton is pressed to the Blue Dot to perform a transaction, the Coprocessor would first verify that this button belongs to the system, i.e. that it knows the same authentication secret (example: a Visa terminal making sure the iButton had a Visa account installed). Then the Coprocessor would verify the signed data, probably money, to make sure it was valid. If someone tried to overwrite the money file, even with a previously valid money file (an attempt to 'restore' a previous amount of money), the signed file would be invalid because the signature includes the write cycle counter, which is incremented every time a page is written to. The write cycle counter is read-only and does not roll over, so the previous amount of money could not be restored by rolling the write counter. The Coprocessor verifies the money, then signs a new data file that contains the new amount of money.

There are two secrets involved with the transaction process. The first secret is the authentication secret. It is used to validate a User iButton to a system. The Coprocessor iButton has the system authentication secret installed. On User iButtons, the system authentication secret is merged with binding data and the unique address of the User iButton to create a unique device authentication secret. The second secret is a signing secret. This secret only exists on the Coprocessor iButton, and is used to sign and verify transaction data (i.e. money). These secrets are inaccessible outside the iButton. Once they are installed, they cannot be retrieved.

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
SHAiButtonUser
Version:
1.00
Author:
SKH

Constructor & Destructor Documentation

SHAiButtonCopr ( ) [protected]

No default construct for user apps. Coprocessors, unlike users, are immutable classes, so there is no setiButton for User applications.

See also:
SHAiButtonCopr(OneWireContainer18,String,boolean,int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])
SHAiButtonCopr(OneWireContainer18,String)
SHAiButtonCopr ( OneWireContainer18  l_owc,
String  coprFilename,
boolean  l_formatDevice,
int  l_signPageNumber,
int  l_authPageNumber,
int  l_wspcPageNumber,
int  l_version,
int  l_encCode,
byte  l_serviceFileExt,
byte[]  l_serviceFilename,
byte[]  l_providerName,
byte[]  l_bindData,
byte[]  l_bindCode,
byte[]  l_auxData,
byte[]  l_initialSignature,
byte[]  l_signingChlg,
byte[]  l_signingSecret,
byte[]  l_authSecret 
) throws OneWireException, OneWireIOException

Sets up this coprocessor object based on the provided parameters and saves all of these parameters as the contents of the file coprFilename stored on owc. Then, the system secret and authentication secret are installed on the coprocessor button.

For the proper format of the coprocessor data file, see the document entitled "Implementing Secured D-Identification and E-Payment Applications using SHA iButtons". For the format of TMEX file structures, see Application Note 114.

Parameters:
l_owcThe DS1963S used as a coprocessor.
coprFilenameThe TMEX filename where coprocessor configuration data is stored. Usually, "COPR.0".
l_formatDeviceboolean indicating whether or not the TMEX filesystem of this device should be formatted before the coprocessor data file is stored.
l_signPageNumberpage number used for signing user account data. (Should be page 8, but page 0 is acceptable if you don't need the TMEX directory structure)
l_authPageNumberpage number used for recreating user secret.
l_wspcPageNumberpage number used for storing user secret and recreating authentication MAC.
l_versionversion of the service provided by this coprocessor.
l_encCoderefers to a type of encryption used for user account data stored on user buttons.
l_serviceFileExtthe file extension used for the service file. (An extension of decimal 102 is reserved for Money files).
l_serviceFilenamethe 4-byte name of the user's account data file.
l_providerNamethe name of the provider of this service
l_bindDatathe binding data used to finalize secret installation on user buttons.
l_bindCodethe binding code used to finalize secret installation on user buttons.
l_auxDataany auxilliary or miscellaneous data to be stored on the coprocessor.
l_initialSignaturethe 20-byte initial MAC placed in user account data before generating actual MAC.
l_signingChlgthe 3-byte challenge used for signing user account data.
l_signingSecretthe system signing secret used by the service being installed on this coprocessor.
l_authSecretthe system authentication secret used by the service being installed on this coprocessor.
Exceptions:
OneWireIOExceptionon 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'.
OneWireExceptionon a communication or setup error with the 1-Wire adapter
See also:
SHAiButtonCopr(OneWireContainer18,String)
SHAiButtonCopr ( OneWireContainer18  owc,
String  coprFilename 
) throws OneWireException, OneWireIOException

Sets up this coprocessor object based on the contents of the file coprFilename stored on owc. This sets all the properties of the object as a consequence of what's in the coprocessor file.

For the proper format of the coprocessor data file, see the document entitled "Implementing Secured D-Identification and E-Payment Applications using SHA iButtons". For the format of TMEX file structures, see Application Note 114.

Parameters:
owcThe DS1963S used as a coprocessor
coprFilenameThe TMEX filename where coprocessor configuration data is stored. Usually, "COPR.0".
Exceptions:
OneWireIOExceptionon 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'.
OneWireExceptionon a communication or setup error with the 1-Wire adapter
See also:
SHAiButtonCopr(OneWireContainer18,String,boolean,int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])

Member Data Documentation

boolean DS1961Scompatible = false [protected]

Specifies whether or not this coprocessor is compatible with the DS1961S.

This entails the use of a specifically padded authentication secret.


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