Datasheet

ManualsBrandsMAXIM INTEGRATED ManualsIntegrated Circuits (ICs)4 kBit 256 x 16

AVAILABLE

1 of 23 011002

1.0 Introduction

The purpose of this document is to familiarize 1-Wire

software developers with the APIs for producing

secure SHA applications. There is an API available in both of the major development kits: the 1-Wire

API for Java™ and the 1-Wire Public Domain Kit. This document should serve as both a tutorial for

designing new secure applications with each API, as well as a walkthrough for a deeper understanding of

the demo applications shipped with each development kit.

This document assumes a basic understanding of the SHA iButton

hardware as well as the 1-Wire

protocol for using iButtons. The data sheet for the DS1963S (SHA iButton) is available on the website

(www.maxim-ic.com). Also, there are application notes available that detail the structure of a signed

certificate for eCash systems [AN151, Maxim Digital Monetary Certificates], a high-level protocol for

secure applications [AN157, SHA iButton API Overview], a SHA-1 overview [AN1201, 1-Wire

SHA-1 Overview], and the implementation of a file system for memory devices [AN114, 1-Wire

File Structure].

In any monetary SHA application, the two major components are the coprocessor and the user token. The

coprocessor is a DS1963S initialized for verifying a user token as a member of the system and validating

the user’s certificate. A user’s token is a DS1963S (or comparable 1-Wire device) that carries a monetary

certificate and identifies a user of the system. For each API, this document will give an overview of the

methods used for initializing the coprocessor, initializing the user token, and performing transactions.

Each transaction can be broken down to further steps, which could include authenticating the user,

verifying the transaction data, and updating the transaction data with dynamic information.

For all the code samples in this document, the code boxes with the light gray shading indicate that the

code is the breakdown of a higher-level task to the most detailed of operations. In the 1-Wire API for

Java, this low-level code will use the OneWireContainer18 class. In the Public Domain Kit, it will use

functions from the SHA18.C module.

2.0 SHA Applications with the 1-Wire API for Java

The solution for SHA Applications in the 1-Wire API for Java introduces a new package into the

development kit: com.dalsemi.onewire.application.sha. A snapshot of the classes in that package, as well

as their inheritance relationships, is shown in Figure 1. When detailing the nature of the necessary

methods introduced in that package, the container-level methods will be considered atomic and no further

breakdown will be provided (although the source is available in the kit).

The SHATransaction abstract superclass is meant to represent all secure transactions. This class defines

three key methods, which represent the fundamental steps in a typical transaction:

1) Verify that the user token is a valid member of the system (verifyUser)

2) Verify that the data is properly certified and has not been tampered with (verifyTransactionData)

3) Update the data as necessary and ensure the token receives the update (executeTransaction)

pplication Note 156

DS1963S SHA 1-Wire API Users Guide

1-Wire and iButton are registered trademarks of Dallas Semiconductor.

Java is a trademark of Sun Microsystems.

Summary of content (23 pages)

PAGE 1
LE AVAILAB Application Note 156 DS1963S SHA 1-Wire API Users Guide 1.0 Introduction The purpose of this document is to familiarize 1-Wire® software developers with the APIs for producing secure SHA applications. There is an API available in both of the major development kits: the 1-Wire API for Java™ and the 1-Wire Public Domain Kit.
PAGE 2
AN156 There are two sample transactions that extend SHATransaction: SHADebit and SHADebitUnsigned. The first implements an account debit system, where an initial account balance is stored in a signed monetary certificate (see AN151). During typical use, a user is validated as a member of the system and the signature on the certificate is verified.
PAGE 3
AN156 is something that isn't important to the specific system, the SHAiButtonUser class could easily be extended to support 1-Wire memory devices, which would just carry signed account information. Note that using other memory devices rules out the use of a challenge-response protocol for authenticating the iButton. There is still a minimal level of security in the user token's 64-bit ROM ID. 2.
PAGE 4
AN156 Although there are a few other parameters for a system that are stored in the service configuration file, these are the most essential parameters. The name of the provider and the version number of the system, for example, are not necessary for a minimal-functionality debit application. Initializing the coprocessor can be done by simply calling the constructor for SHAiButtonCopr, passing all the parameters as arguments.
PAGE 5
AN156 If the SHA coprocessor will be used to authenticate DS1961S/DS2432 iButtons or to produce the copyscratchpad authorization, the master authentication secret will have to be padded to accommodate the DS1961S’s smaller scratchpad. A utility function is provided which will pad the secret appropriately. Then the “DS1961S compatibility flag” in the coprocessor file should be set to a non-zero value. Padding the Authentication Secret Figure 5 inputAuthSecret = SHAiButtonCopr.
PAGE 6
AN156 Container-Level Installation of Authentication Secret in User Token Figure 7 /* Create the empty file on the user token */ OWFile owf = new OWFile(owc18, “DLSM.102”); owf.format(); owf.createNewFile(); /* Get the page number the account file will be stored on */ int acctPage = owf.getPageList()[0]; owf.close(); /* Install the master authentication secret, same as on the coprocessor */ owc18.
PAGE 7
AN156 certificate to the data page. The current value of the write cycle counter is then incremented by 1, since the data that it will be verified with is about to be written. The certificate’s signature is produced on the coprocessor using the Sign Data command. The command has a few variable inputs. The first of which is the data page that is to be signed. In this case, that page is the actual account file (as constructed in Figure 9), which is written to the signing page of the scratchpad.
PAGE 8
AN156 Signing Data with Coprocessor at Container-Level Figure 13 /* write the account data to the signing page of the coprocessor */ coprDevice.writeDataPage(signPageNumber, acctData); /* write the signScratchpad to the scratchpad of the coprocessor */ coprDevice.writeScratchpad(signPageNumber, 0, acctData, 0, 32); /* sign the data and read the signature*/ coprDevice.SHAFunction(coprDevice.SIGN_DATA_PAGE, signPageNumber << 5); coprDevice.
PAGE 9
AN156 Using SHAiButtonCopr and SHAiButtonUser for Authentication Figure 16 /* Use coprocessor to generate a random challenge */ copr.generateChallenge(0, challenge, 0); /* issue challenge to user getting back the account data, response MAC, and the * value of the write-cycle counter */ int wcc = user18.
PAGE 10
AN156 Answering a Random Challenge with a DS1963S User Token Figure 18 /* Write the challenge to the scratchpad of the user token */ owc18.writeScratchpad(acctPage, 0, scratchpad, 0, 32); /* reads 42 bytes = 32 bytes of page data * + 4 bytes page counter * + 4 bytes secret counter * + 2 bytes CRC */ owc18.
PAGE 11
AN156 2.4 Validating the User’s Certificate Validating a certificate from a user token looks a lot like the earlier section on initializing the data. The steps for signing the data are very similar, but the coprocessor-generated signature is merely matched against the existing signature, rather than being read into the certificate. Also, since the entire certificate is merely stored on a file in any user token, the process for validating the certificate is identical across all tokens.
PAGE 12
AN156 Container-Level Validation of the Certificate Signature Figure 22 /* save the data signature */ byte[] dataSignature = new byte[20]; System.arraycopy(acctData, 2, dataSignature, 0, 20); /* clear out the old signature and CRC 16 */ copr.
PAGE 13
AN156 3.0 SHA Applications with the 1-Wire Public Domain Kit The solution for SHA Applications in the 1-Wire Public Domain Kit introduces a few new modules into the development kit. Figure 24 is a listing of the new modules. SHA API Functions Figure 24 SHA18.C (Device Layer) ReadScratchpadSHA18 – Reads the scratchpad of DS1963S with CRC16 verification. WriteScratchpadSHA18 – Writes the scratchpad of DS1963S with CRC16 verification. CopyScratchpadSHA18 – Copies the scratchpad of DS1963S with verification.
PAGE 14
AN156 The SHAUser structure is used to maintain all pertinent information about a specific user token. Also, it maintains state between successive calls to API functions. For example, the accountFile field is populated when verifyUser is called, so the verifyData method uses this information for verifying the certificate signature without re-reading the device.
PAGE 15
AN156 The following blocks of code demonstrate the steps necessary for initializing the coprocessor. Each block of code is well commented and the declarations, though not necessarily the initialization, of all variables used are shown. The intent is that the code can be copied into a project and compiled after just a few edits. This first block shows the declaration, but not the initialization, of the most important properties.
PAGE 16
AN156 Initializing the Coprocessor Figure 29 /* Find the first SHA device on the 1-Wire Net */ FindNewSHA(copr.portnum, copr.devAN, FALSE); /* Install the master authentication secret and the master signing secret */ InstallSystemSecret18(copr.portnum, copr.signPageNumber, copr.signPageNumber&7, inputSignSecret, 47, FALSE)) InstallSystemSecret18(copr.portnum, copr.authPageNumber, copr.
PAGE 17
AN156 Then, the page number from the directory entry specifies the page where the master authentication secret should be installed and bound to the user token. When the certificate is actually written to the device, it is done with a direct page write, rather than using the file API. This will allow for much faster updates (very important in a responsive debit application) when actually debiting the token. Using the SHADEBIT.
PAGE 18
AN156 unsigned certificate is when using a DS1961S/DS2432, which requires knowledge of the secret to write to it. Whether signed or unsigned, the format of the certificate remains the same. Figure 32 illustrates how to manually format a certificate file as specified in AN151. Creating a New Certificate Figure 32 /* eCertificate, see format in AN151 */ uchar acctData[32]; acctData[0] = 29; // file length acctData[1] = 0x01; // data type code or algorithm (0x01 dynamic eCash) memcpy(acctData, copr.
PAGE 19
AN156 Signing Data with SHAIB.C Module Figure 34 /* sign the data with the coprocessor and set the value of certificate signature */ CreateDataSignature(copr, user->accountFile.raw, signScratchpad, user->accountFile.file.signature, TRUE); The helper method shown in Figure 34 can be broken down into the necessary low-level methods used to implement signing data. Figure 35 illustrates this process for creating a data signature Signing Data with Coprocessor with SHA18 Module Figure 35 int addr = copr.
PAGE 20
AN156 the serial number of the user token, and the random challenge. The coprocessor is then used to reproduce this SHA result, ensuring that the user token is a valid member of the system. Authenticating User Token with SHADEBIT.C Module Figure 37 /* Verify user tokens authentication response, same for signed and unsigned */ VerifyUser(copr, user, TRUE); The process for verifying a user is the same for both signed and unsigned transactions.
PAGE 21
AN156 Answering a Random Challenge with a DS1963S User Token Figure 40 int acctAddr = user.accountPageNumber<<5; //physical address of account file uchar scratchpad[32]; memcpy(&scratchpad[20], chlg, 3); /* Write the challenge to the scratchpad of the user token */ EraseScratchpadSHA18(user.portnum, acctAddr, FALSE); WriteScratchpadSHA18(user.portnum, acctAddr, scratchpad, 32, TRUE); /* perform authenticated read to get the page data and the resulting MAC */ user.writeCycleCounter = ReadAuthPageSHA18(user.
PAGE 22
AN156 3.4 Validating the User’s Certificate Validating a certificate from a user token looks a lot like the earlier section on initializing the data. The steps for signing the data are very similar, but the coprocessor-generated signature is merely matched against the existing signature, rather than being read into the certificate. Also, since the entire certificate is merely stored on a file in any user token, the process for validating the certificate is identical across all tokens.
PAGE 23
AN156 Validating the Certificate Signature Figure 44 int signAddr = copr.signPageNumber<<5; // physical address of signing page int wcc = user.writeCycleCounter; uchar scratchpad[32]; /* save the data signature */ uchar dataSignature[20]; memcpy(dataSignature, user.accountFile.file.signature, 20); /* clear out the old signature and CRC 16 */ memcpy(user.accountFile.file.signature, copr.initSignature, 20); user.accountFile.file.crc16[0] = 0x00; user.accountFile.file.