Dallas Semiconductor 1-Wire API 1.00 Alpha: Class SHAiButtonCoprVM

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.dalsemi.onewire.application.sha
Class SHAiButtonCoprVM

    java.lang.Object
      |
      +--com.dalsemi.onewire.application.sha.SHAiButtonCopr
            |
            +--com.dalsemi.onewire.application.sha.SHAiButtonCoprVM

public class SHAiButtonCoprVM
extends SHAiButtonCopr

Class for simulating an instance of a 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.

With this class, no DS1963S SHA iButton is necessary for the coprocessor in SHA Transactions. The simulated Coprocessor iButton verifies signatures and signs data for User iButtons.

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.

Version:
  1.00
See Also:
  `SHATransaction`, `SHAiButtonUser`, `SHAiButtonCopr`

Fields inherited from class com.dalsemi.onewire.application.sha.SHAiButtonCopr
`BIND_SECRET_FAILED, COPY_SCRATCHPAD_FAILED, ERASE_SCRATCHPAD_FAILED, MATCH_SCRATCHPAD_FAILED, NO_ERROR, SHA_FUNCTION_FAILED, WRITE_DATA_PAGE_FAILED, WRITE_SCRATCHPAD_FAILED`

Constructor Summary
`SHAiButtonCoprVM(byte[] RomID, 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)` Sets up this simulated coprocessor based on the provided parameters.
`SHAiButtonCoprVM(OneWireContainer18 owc, String filename, byte[] sign_secret, byte[] auth_secret)` Simulates a specific DS1963S coprocessor device.
`SHAiButtonCoprVM(OneWireContainer owc, String filename)` Loads a simulated DS1963S coprocessor device from any 1-Wire memory device supported by the 1-Wire File I/O API.
`SHAiButtonCoprVM(OneWireContainer owc, String filename, byte[] sign_secret, byte[] auth_secret)` Loads a simulated DS1963S coprocessor device from any 1-Wire memory device supported by the 1-Wire File I/O API.
`SHAiButtonCoprVM(String filename)` Loads a simulated DS1963S coprocessor device from disk.
`SHAiButtonCoprVM(String filename, byte[] sign_secret, byte[] auth_secret)` Loads a simulated DS1963S coprocessor device from disk.

Method Summary
`boolean` | `bindSecretToiButton(int pageNum, byte[] bindData, byte[] bindCode, int secretNum)` Binds an installed secret to this virtual DS1963S by using well-known binding data and this DS1963S's (unique?) address.
`boolean` | `createDataSignature(byte[] accountData, byte[] signScratchpad, byte[] mac_buffer, int macStart)` Given a 32-byte array for page data and a 32-byte array for scratchpad content, this function will create a 20-byte signature for the data based on SHA-1.
`boolean` | `createDataSignatureAuth(byte[] accountData, byte[] signScratchpad, byte[] mac_buffer, int macStart, byte[] fullBindCode)` Creates a data signature, but instead of using the signing secret, it uses the authentication secret, bound for a particular button.
`boolean` | `generateChallenge(int offset, byte[] ch, int start)` Generates a 3 byte random challenge in the iButton, sufficient to be used as a challenge to be answered by a User iButton.
`boolean` | `installMasterSecret(int pageNum, byte[] secret, int secretNum)` Installs a secret on this virtual DS1963S.
`boolean` | `load(OneWireContainer18 owc, String filename)` Loads coprocessor configuration information from a standard TMEX service file on a DS1963S.
`boolean` | `load(OneWireContainer owc, String filename)` Loads coprocessor configuration information from an (almost) standard service TMEX file on 1-Wire memory device.
`boolean` | `load(String filename)` Loads coprocessor configuration information from an (almost) standard service file on hard drive.
`boolean` | `save(OneWireContainer owc, String filename, boolean saveSecretData)` Saves simulated coprocessor configuration info to an (almost) standard-format to a 1-Wire Memory Device's TMEX file.
`boolean` | `save(String filename, boolean saveSecretData)` Saves simulated coprocessor configuration info to an (almost) standard-format to a hard drive file.
`String` | `toString()` Returns a string representing the 1-Wire address of this SHAiButton.
`boolean` | `verifyAuthentication(byte[] fullBindCode, byte[] pageData, byte[] scratchpad, byte[] verify_mac, byte authCmd)` Determines if a `SHAiButtonUser` belongs to the system defined by this Coprocessor iButton.See the usage example in this class for initializing a Coprocessor iButton.
`boolean` | `verifySignature(byte[] pageData, byte[] scratchpad, byte[] verify_mac)` Verifies a User iButton's signed data on this Coprocessor iButton.

Methods inherited from class com.dalsemi.onewire.application.sha.SHAiButtonCopr
`getAddress, getAddress, getAddress, getAuthenticationPageNumber, getAuxilliaryData, getBindCode, getBindCode, getBindData, getBindData, getEncryptionCode, getFilename, getFilenameExt, getInitialSignature, getInitialSignature, getLastError, getProviderName, getSigningChallenge, getSigningChallenge, getSigningPageNumber, getVersion, getWorkspacePageNumber, isDS1961Scompatible, reformatFor1961S`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### SHAiButtonCoprVM

    public SHAiButtonCoprVM(byte[] RomID,
                            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 simulated coprocessor based on the provided parameters. Then, the system secret and authentication secret are installed on the simulated coprocessor iButton.

  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:
    `RomID` - The address for the simulated coprocessor.
    `l_signPageNumber` - page 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_authPageNumber` - page number used for recreating user secret.
    `l_wspcPageNumber` - page number used for storing user secret and recreating authentication MAC.
    `l_version` - version of the service provided by this coprocessor.
    `l_encCode` - refers to a type of encryption used for user account data stored on user buttons.
    `l_serviceFileExt` - the file extension used for the service file. (An extension of decimal 102 is reserved for Money files).
    `l_serviceFilename` - the 4-byte name of the user's account data file.
    `l_providerName` - the name of the provider of this service
    `l_bindData` - the binding data used to finalize secret installation on user buttons.
    `l_bindCode` - the binding code used to finalize secret installation on user buttons.
    `l_auxData` - any auxilliary or miscellaneous data to be stored on the coprocessor.
    `l_initialSignature` - the 20-byte initial MAC placed in user account data before generating actual MAC.
    `l_signingChlg` - the 3-byte challenge used for signing user account data.
    `l_signingSecret` - the system signing secret used by the service being installed on this coprocessor.
    `l_authSecret` - the system authentication secret used by the service being installed on this coprocessor.
  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:
    `SHAiButtonCoprVM(String)`, `SHAiButtonCoprVM(String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer,String)`, `SHAiButtonCoprVM(OneWireContainer,String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer18,String,byte[],byte[])`

### SHAiButtonCoprVM

    public SHAiButtonCoprVM(String filename)
                     throws OneWireException,
                            OneWireIOException

  Loads a simulated DS1963S coprocessor device from disk. The given file name is loaded to get all the parameters of the coprocessor. It is assumed that the secrets were stored in the file when the simulated coprocessor's data was saved to disk.

  Parameters:
    `filename` - The filename of the simulated coprocessor's data file ("shaCopr.dat")
  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:
    `SHAiButtonCoprVM(String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer,String)`, `SHAiButtonCoprVM(OneWireContainer,String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer18,String,byte[],byte[])`, `SHAiButtonCoprVM(byte[],int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])`

### SHAiButtonCoprVM

    public SHAiButtonCoprVM(String filename,
                            byte[] sign_secret,
                            byte[] auth_secret)
                     throws OneWireException,
                            OneWireIOException

  Loads a simulated DS1963S coprocessor device from disk. The given file name is loaded to get all the parameters of the coprocessor. After it is loaded, the given secrets are installed.

  Parameters:
    `filename` - The filename of the simulated coprocessor's data file ("shaCopr.dat")
    `sign_secret` - The system data signing secret.
    `auth_secret` - The system device authentication secret.
  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:
    `SHAiButtonCoprVM(String)`, `SHAiButtonCoprVM(OneWireContainer,String)`, `SHAiButtonCoprVM(OneWireContainer,String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer18,String,byte[],byte[])`, `SHAiButtonCoprVM(byte[],int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])`

### SHAiButtonCoprVM

    public SHAiButtonCoprVM(OneWireContainer owc,
                            String filename)
                     throws OneWireException,
                            OneWireIOException

  Loads a simulated DS1963S coprocessor device from any 1-Wire memory device supported by the 1-Wire File I/O API. The given file name is loaded to get all the parameters of the coprocessor. It is assumed that the secrets were stored in the file when the simulated coprocessor's data was saved to disk.

  Parameters:
    `owc` - 1-Wire memory device with valid TMEX file system
    `filename` - The filename of the simulated coprocessor's data file ("shaCopr.dat")
  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:
    `SHAiButtonCoprVM(String)`, `SHAiButtonCoprVM(String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer,String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer18,String,byte[],byte[])`, `SHAiButtonCoprVM(byte[],int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])`

### SHAiButtonCoprVM

    public SHAiButtonCoprVM(OneWireContainer owc,
                            String filename,
                            byte[] sign_secret,
                            byte[] auth_secret)
                     throws OneWireException,
                            OneWireIOException

  Loads a simulated DS1963S coprocessor device from any 1-Wire memory device supported by the 1-Wire File I/O API. The given file name is loaded to get all the parameters of the coprocessor. After it is loaded, the given secrets are installed.

  Parameters:
    `owc` - 1-Wire memory device with valid TMEX file system
    `filename` - The filename of the simulated coprocessor's data file ("shaCopr.dat")
    `sign_secret` - The system data signing secret.
    `auth_secret` - The system device authentication secret.
  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:
    `SHAiButtonCoprVM(String)`, `SHAiButtonCoprVM(String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer,String)`, `SHAiButtonCoprVM(OneWireContainer18,String,byte[],byte[])`, `SHAiButtonCoprVM(byte[],int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])`

### SHAiButtonCoprVM

    public SHAiButtonCoprVM(OneWireContainer18 owc,
                            String filename,
                            byte[] sign_secret,
                            byte[] auth_secret)
                     throws OneWireException,
                            OneWireIOException

  Simulates a specific DS1963S coprocessor device. First, the given TMEX file name is loaded of the container to get all the parameters of the coprocessor. Then (since secrets are not readable off the iButton, they must be provided) the secrets are installed on the virtual coprocessor.

  Parameters:
    `owc` - The coprocessor button this VM will simulate.
    `filename` - The TMEX filename of the coprocessor service file ("COPR.0")
    `sign_secret` - The system data signing secret.
    `auth_secret` - The system device authentication secret.
  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:
    `SHAiButtonCoprVM(String)`, `SHAiButtonCoprVM(String,byte[],byte[])`, `SHAiButtonCoprVM(OneWireContainer,String)`, `SHAiButtonCoprVM(OneWireContainer,String,byte[],byte[])`, `SHAiButtonCoprVM(byte[],int,int,int,int,int,byte,byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[],byte[])`

Method Detail

### save

    public boolean save(String filename,
                        boolean saveSecretData)
                 throws OneWireException,
                        OneWireIOException

  Saves simulated coprocessor configuration info to an (almost) standard-format to a hard drive file.

  Parameters:
    `filename` - The filename of the simulated coprocessor's data file ("shaCopr.dat")
    `saveSecretData` - If `true, the raw secret information is also written to the file`
  Returns:
    `true` if the info was successfully saved
  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

### save

    public boolean save(OneWireContainer owc,
                        String filename,
                        boolean saveSecretData)
                 throws OneWireException,
                        OneWireIOException

  Saves simulated coprocessor configuration info to an (almost) standard-format to a 1-Wire Memory Device's TMEX file.

  Parameters:
    `owc` - 1-Wire Memory Device with valid TMEX file structure.
    `filename` - The TMEX filename of the simulated coprocessor's data file ("COPR.2")
    `saveSecretData` - If `true, the raw secret information is also written to the file.`
  Returns:
    `true` if the info was successfully saved
  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

### load

    public boolean load(String filename)

  Loads coprocessor configuration information from an (almost) standard service file on hard drive. If secret information was saved, this routine automatically loads it.

  Parameters:
    `filename` - The filename of the simulated coprocessor's data file ("shaCopr.dat")
  Returns:
    `true` if the info was successfully loaded

### load

    public boolean load(OneWireContainer owc,
                        String filename)

  Loads coprocessor configuration information from an (almost) standard service TMEX file on 1-Wire memory device. If secret information was saved, this routine automatically loads it.

  Parameters:
    `owc` - 1-Wire memory device with valid TMEX file structure
    `filename` - The TMEX filename of the simulated coprocessor's data file ("COPR.2")
  Returns:
    `true` if the info was successfully loaded

### load

    public boolean load(OneWireContainer18 owc,
                        String filename)

  Loads coprocessor configuration information from a standard TMEX service file on a DS1963S.

  Parameters:
    `owc` - DS1963S set up as a valid coprocessor
    `filename` - The TMEX filename of the coprocessor's data file ("COPR.0")
  Returns:
    `true` if the info was successfully loaded

### createDataSignature

    public boolean createDataSignature(byte[] accountData,
                                       byte[] signScratchpad,
                                       byte[] mac_buffer,
                                       int macStart)
                                throws OneWireException,
                                       OneWireIOException

  Given a 32-byte array for page data and a 32-byte array for scratchpad content, this function will create a 20-byte signature for the data based on SHA-1. The format of the calculation of the data signature is as follows: First 4-bytes of signing secret, 32-bytes of accountData, 12 bytes of scratchpad data starting at index 8, last 4-bytes of signing secret, 3 bytes of scratchpad data starting at index 20, and the rest is padding as specified for standard SHA-1. This is all laid out, in detail, in the DS1963S data sheet.

  The resulting 20-byte signature is copied into `mac_buffer` starting at `macStart`. If you're updating a signature that already exists in the accountData array, it is acceptable to call the method like so: ``

         copr.createDataSignature(accountData, spad, accountData, 8);

  assuming that the signature starts at index 8 of the accountData array.
  Overrides:
    `createDataSignature` in class `SHAiButtonCopr`
  Parameters:
    `accountData` - the 32-byte data page for which the signature is generated.
    `signScratchpad` - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
    `mac_buffer` - used to return the 20-byte signature generated by signing the page using the coprocessor's system signing secret.
    `macStart` - the offset into mac_buffer where copying should start.
  Returns:
    `true` if successful, `false` if an error occurred (use `getLastError()` for more information on the type of error)
  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:
    `OneWireContainer18.SHAFunction(byte,int)`, `SHAiButtonCopr.getLastError()`

### generateChallenge

    public boolean generateChallenge(int offset,
                                     byte[] ch,
                                     int start)
                              throws OneWireIOException,
                                     OneWireException

  Generates a 3 byte random challenge in the iButton, sufficient to be used as a challenge to be answered by a User iButton. The user answers the challenge with an authenticated read of it's account data.

  The DS1963S will generate 20 bytes of pseudo random data, though only 3 bytes are needed for the challenge. Programs can add more 'randomness' by selecting different bytes from the 20 bytes of random data using the `offset` parameter.

  The random number generator is actually the DS1963S's SHA engine, which requires page data to compute a hash. Select a page number with the `page_number` parameter.

  Overrides:
    `generateChallenge` in class `SHAiButtonCopr`
  Parameters:
    `offset` - offset into the 20 random bytes to draw random data from (must be in range 0-16)
    `ch` - buffer for the challenge to be returned (must be of length 3 or more)
    `start` - the starting index into array `ch` to begin copying the challenge bytes.
  Returns:
    `true` if successful, `false` if an error occurred (use `getLastError()` for more information on the type of error)
  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:
    `SHAiButtonUser.readAccountData(byte[],int,byte[],int,byte[],int)`, `SHAiButtonCopr.getLastError()`

### verifyAuthentication

    public boolean verifyAuthentication(byte[] fullBindCode,
                                        byte[] pageData,
                                        byte[] scratchpad,
                                        byte[] verify_mac,
                                        byte authCmd)
                                 throws OneWireIOException,
                                        OneWireException

  Determines if a `SHAiButtonUser` belongs to the system defined by this Coprocessor iButton.See the usage example in this class for initializing a Coprocessor iButton.

  The first step in user authentication is to recreate the user's unique secret on the coprocessor button using `bindSecretToiButton(int,byte[],byte[],int)`. Then the coprocessor signs the pageData to produce a MAC. If the MAC matches that produced by the user, the user belongs to the system.

  The TMEX formatted page with the user's account data is in the 32-byte parameter `pageData`. If the verification is successful, the data data signature must still be verified with the `verifySignature()` method.

  Failure of this method does not necessarily mean that the User iButton does not belong to the system. It is possible that a communication disruption here could cause a CRC error that would be indistinguishable from a failed authentication. However, repeated attempts should reveal whether it was truly a communication problem or a User iButton that does not belong to the system.

  Overrides:
    `verifyAuthentication` in class `SHAiButtonCopr`
  Parameters:
    `fullBindCode` - 15-byte binding code used to recreate user iButtons unique secret in the coprocessor.
    `pageData` - 32-byte buffer containing the data page holding the user's account data.
    `scratchpad` - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
    `verify_mac` - the 20-byte buffer containing the user's authentication response to the coprocessor's challenge.
  Returns:
    `true` if the operation was successful and the user's MAC matches that generated by the coprocessor.
  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:
    `generateChallenge(int,byte[],int)`, `verifySignature(byte[],byte[],byte[])`, `bindSecretToiButton(int,byte[],byte[],int)`, `OneWireContainer18.SHAFunction(byte,int)`, `OneWireContainer18.matchScratchPad(byte[])`, `SHAiButtonCopr.getLastError()`

### createDataSignatureAuth

    public boolean createDataSignatureAuth(byte[] accountData,
                                           byte[] signScratchpad,
                                           byte[] mac_buffer,
                                           int macStart,
                                           byte[] fullBindCode)
                                    throws OneWireException,
                                           OneWireIOException

  Creates a data signature, but instead of using the signing secret, it uses the authentication secret, bound for a particular button.

  `fullBindCode` is ignored by the Coprocessor VM. Instead of binding the secret to the signing page, the coprocessor VM "cheats" and lets you sign the workspace page, where (presumably) the secret is already bound.

  Overrides:
    `createDataSignatureAuth` in class `SHAiButtonCopr`
  Parameters:
    `accountData` - the 32-byte data page for which the signature is generated.
    `signScratchpad` - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
    `mac_buffer` - used to return the 20-byte signature generated by signing the page using the coprocessor's system signing secret.
    `macStart` - the offset into mac_buffer where copying should start.
    `fullBindCode` - ignored by simulated coprocessor
  Returns:
    `true` if successful, `false` if an error occurred (use `getLastError()` for more information on the type of error)
  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:
    `OneWireContainer18.SHAFunction(byte,int)`, `createDataSignature(byte[],byte[],byte[],int)`, `SHAiButtonCopr.getLastError()`

### verifySignature

    public boolean verifySignature(byte[] pageData,
                                   byte[] scratchpad,
                                   byte[] verify_mac)
                            throws OneWireIOException,
                                   OneWireException

  Verifies a User iButton's signed data on this Coprocessor iButton. The Coprocessor must recreate the signature based on the data in the file and the contents of the given scratchpad, and then match that with the signature passed in verify_mac.

  Overrides:
    `verifySignature` in class `SHAiButtonCopr`
  Parameters:
    `pageData` - the full 32 byte TMEX file from the User iButton (from `verifyAuthentication`) with the
    `scratchpad` - the 32-byte scratchpad contents for which the signature is generated. This will contain parameters such as the user's write cycle counter for the page, the user's 1-wire address, and the page number where account data is stored.
    `verify_mac` - the 20-byte buffer containing the signature the user had stored with the account data file.
  Returns:
    `true`if the data file is valid, `false` if an error occurred (use `getLastError()` for more information on the type of error)``
  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:
    `verifyAuthentication(byte[],byte[],byte[],byte[],byte)`, `SHAiButtonCopr.getLastError()`

### bindSecretToiButton

    public boolean bindSecretToiButton(int pageNum,
                                       byte[] bindData,
                                       byte[] bindCode,
                                       int secretNum)

  Binds an installed secret to this virtual DS1963S by using well-known binding data and this DS1963S's (unique?) address. This makes the secret unique for this iButton. Coprocessor iButtons use this method to recreate the iButton's secret to verify authentication. Roving iButtons use this method to finalize their secret keys.

  Note that unlike in the `installMasterSecret()` method, the page number does not need to be equivalent to the `secret_number` modulo 8. The new secret (installed secret + binding code) is generated from this page but can be copied into another secret. User iButtons should bind to the same page the secret was installed on. Coprocessor iButtons must copy to a new secret to preserve the general system authentication secret.

  The binding should be either 7 bytes long or 15 bytes long. A 15-length `byte` array is unaltered and placed in the scratchpad for the binding. A 7-length `byte` array is combined with the page number and DS1963S unique address and then placed in the scratchpad. Coprocessors should use a pre-formatted 15-length `byte` array. User iButtons should let the method format for them (i.e. use the 7-length `byte` array option).

  Parameters:
    `page` - the page number that has the master secret already installed
    `bind_data` - 32 bytes of binding data used to bind the iButton to the system
    `bind_code` - the 7-byte or 15-byte binding code
    `secret_number` - secret number to copy the resulting secret to
  Returns:
    `true` if successful
  See Also:
    `installMasterSecret(int,byte[],int)`

### installMasterSecret

    public boolean installMasterSecret(int pageNum,
                                       byte[] secret,
                                       int secretNum)

  Installs a secret on this virtual DS1963S. The secret is written in partial phrases of 47 bytes (32 bytes to a memory page, 15 bytes to the scratchpad) and is cumulative until the entire secret is processed. Secrets are associated with a page number. See the datasheet for more information on this association.

  In most cases, `page` should be equal to `secret_number` or `secret_number+8`, based on the association of secrets and page numbers. A secret is 8 bytes and there are 8 secrets. These 8 secrets are associated with the first 16 pages of memory.

  On TINI, this method will be slightly faster if the secret's length is divisible by 47. However, since secret key generation is a part of initialization, it is probably not necessary.

  Parameters:
    `page` - the page number used to write the partial secrets to
    `secret` - the entire secret to be installed
    `secret_number` - the secret 'page' to use (0 - 7)
  Returns:
    `true` if successful
  See Also:
    `bindSecretToiButton(int,byte[],byte[],int)`

### toString

    public String toString()

  Returns a string representing the 1-Wire address of this SHAiButton.
  Overrides:
    `toString` in class `SHAiButtonCopr`
  Returns:
    a string containing the 8-byte address of this 1-Wire device.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD