DS1963S-F5+ Datasheet DS1963S-F5+ | P13-P15

AN156

13 of 23

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.

MatchScratchpadSHA18 – Matches the contents of the scratchpad with given MAC.

EraseScratchpadSHA18 – Erases the scratch of DS1963S.

ReadAuthPageSHA18 – Performs a Read Authenticated Page command on DS1963S.

ReadMemoryPageSHA18 – Reads a page of memory from DS1963S.

WriteDataPageSHA18 – Writes a page of memory to DS1963S.

SHAFunction18 – Executes a given SHA function on DS1963S (i.e. Sign Data Page, Auth. Host)

InstallSystemSecret18 – Installs a master secret onto DS1963S.

BindSecretToiButton18 – Creates unique DS1963S secret with master secret and binding data.

CopySecretSHA18 – Copies 8-bytes of a SHA result into secret memory.

SHAIB.C (Protocol Layer)

SelectSHA – Accesses SHA Device on 1-Wire Net and forces overdrive.

FindNewSHA – Loops to find all SHA Devices on 1-Wire Net while blocking for arrivals.

FindUserSHA – Finds all SHA devices with the specified user account file.

FindCoprSHA – Finds all SHA devices with the specified coprocessor file.

GetCoprFromRawData – Loads service setup data from raw bytes, probably from a file.

CreateChallenge – Creates a random challenge using the Generate Challenge SHA command.

AnswerChallenge – Writes challenge to scratchpad of a user token and reads the account info.

VerifyAuthResponse – Verifies the authentication response of a user token.

CreateDataSignature – Creates a data signature using Sign Data Page SHA command.

SHADEBIT.C (Transaction Layer)

InstallServiceData – Formats the user token and installs a new certificate.

UpdateServiceData – Signs certificate information and writes it to the user token.

VerifyUser – Challenges user token with random challenge and verifies the response.

VerifyData – Verifies the certificate signature.

ExecuteTransaction – Debits user’s account balance and verifies that user received the update.

In the file SHAIB.H, there are 3 structures that define the coprocessor, the user, and the certificate. Figure

25 shows the format of the certificate.

struct DebitFile Figure 25

typedef struct { // See AN151 for certificate details

uchar fileLength; // length of this file

uchar dataTypeCode; // data type code – 0x01 for dynamic, 0x02 for static

uchar signature[20]; // 20-byte data signature for this certificate

uchar convFactor[2]; // country code and multiplier

uchar balanceBytes[3]; // account balance

uchar transID[2]; // transaction ID

uchar contPtr; // file continuation pointer

uchar crc16[2]; // crc16 of file

} DebitFile;

AN156

14 of 23

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.

struct SHAUser Figure 26

The SHACopr structure is used to maintain all system parameters. These parameters are, typically, stored

in a file on the coprocessor device.

struct SHACopr Figure 27

3.1 Initializing the Coprocessor

Initializing the coprocessor consists of two important steps: installing the system authentication secret and

installing the system signing secret. An optional third step is to write all of the system configuration data

to the iButton in the form of a file (see AN114). The configuration data doesn’t have to be stored on the

coprocessor iButton, but it’s convenient to keep the system parameters as portable as the coprocessor. As

an alternative, the file can be stored on a disk drive or the parameters can be hardcoded in your

application.

typedef struct {

// portnum and address of the device

int portnum;

uchar devAN[8];

uchar accountPageNumber; // page the user's account file is stored on

long writeCycleCounter; // Write cycle counter for account page

uchar responseMAC[20]; // MAC from Read Authenticated Page command

union {

uchar raw[32]; // used for direct writes to button only

DebitFile file; // use this for accessing individual fields

} accountFile;

} SHAUser;

typedef struct {

// portnum and address of the device

int portnum;

uchar devAN[8];

uchar serviceFilename[5]; // name of the account file stored on the user token

uchar signPageNumber; // memory page used for signing data (0 or 8)

uchar authPageNumber; // memory page used for storing master authentication secret

uchar wspcPageNumber; // memory page used for storing user's unique secret

uchar versionNumber; // version number of the transaction system.

uchar bindCode[7]; // Scratchpad binding data for producing unique secrets

uchar bindData[32]; // Data page binding data for producing unique secrets

uchar signChlg[3]; // signature used when signing account data

uchar initSignature[20]; // challenge used when signing account data

uchar* providerName; // name of the transaction system provider

uchar* auxilliaryData; // any other pertinent information

uchar encCode; // encryption code

uchar ds1961Scompatible; // indicates that secret was padded for DS1961S

} SHACopr;

AN156

15 of 23

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.

Necessary System Parameters for a SHA Application Figure 28

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.

/* The input data to be used for calculating the master authentication and signing

* secrets. The calculation involves splitting the secret into blocks of 47 bytes

* (32 bytes to the data page, 15 bytes to the scratchpad) and then performing the

* SHA command Compute First Secret, followed by Compute Next Secret for each 47

* byte block after the first. */

uchar inputAuthSecret[47], inputSignSecret[47]; // . . . initialize from user input

/* The coprocessor */

SHACopr copr;

copr.portnum = 0;

/* Name of the account file (and file extension) to create on user tokens */

memcpy(copr.serviceFilename, “DLSM”, 4);

copr.serviceFilename[4] = 102; // extension for money files

/* The page to use for the signing secret must be page 8, because secret 0 is the

* only secret that can be used for the SHA command Sign Data Page. For a list of

* SHA commands, and what pages they can be used on, see the DS1963S datasheet. */

copr.signPageNumber = 8;

/* The authentication secret can be on any page as long as it doesn’t collide with

* the file holding coprocessor configuration information and not secret 0 */

copr.authPageNumber = 7;

/* The workspace page is the page the coprocessor will use for recreating a user’s

* unique authentication secret and it’s authentication response. */

copr.wspcPageNumber = 9;

/* The binding information is used to create the “unique” secret for each button.

* bindData is written to the data page of the user token, and bindCode is written

* to the scratchpad. The result of a Compute Next Secret using the system

* authentication secret, the account page number, the rom ID of the user token, the

* bind data, and the bind code becomes the user’s unique authentication secret.

* This is used to initialize a user token and the coprocessor must use the same

* data to recreate the user token’s unique secret. */

copr.bindData = //32 bytes

copr.bindCode = //7 bytes

/* Initial signature to use when signing the certificate */

copr.initSignature = // 20 bytes of user input

/* Three byte challenge used when signing the certificate */

copr.signingChlg = // 3 bytes

P1-P3 P4-P6 P7-P9 P10-P12 P13-P15 P16-P18 P19-P21 P22-P23

DS1963S-F5+

Mfr. #:

Buy DS1963S-F5+

Manufacturer:

Maxim Integrated

Description:

iButtons & Accessories SHA iButton

Lifecycle:

New from this manufacturer.

Delivery:

DHL FedEx Ups TNT EMS

Payment:

T/T Paypal Visa MoneyGram Western Union

Products related to this Datasheet

DS1963S-F5+