DS1963S-F5+ Datasheet DS1963S-F5+ | P16-P18

AN156

16 of 23

Initializing the Coprocessor Figure 29

3.2 Initializing the User Token

Initializing the user token consists of two steps. First, install the master authentication secret and bind it to

the iButton to produce the unique secret for the token. Second, write the certificate file to the iButton. It is

actually a little more complicated than it may initially sound. The DS1963S has eight secrets that

correspond to the 16 pages of memory (where each secret is shared by two pages). The certificate file

must be written to a page which has a write cycle counter, which limits it to the last eight pages of the

device’s memory banks. Also, the certificate file must be written to one of the pages whose corresponding

secret is the secret where the master authentication secret was installed. But, the 1-Wire file API doesn’t

allow the specification of a page number for the file to be stored on. The best that can be done is to give

the file one of the reserved extensions that ensures special treatment. Extensions 101 and 102, for

example, are reserved for files that must be written on pages with write cycle counters if the device has

them (see AN114). One solution for this is to use the 1-Wire file API to create an empty stub file to write

the certificate. This creates the proper directory entries for the certificate so it can be located dynamically.

/* 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.authPageNumber&7,

inputAuthSecret, 47, TRUE))

/* prepare the service file to write to the coprocessor */

int namelen = strlen(copr.providerName);

int auxlen = strlen(copr.auxilliaryData);

uchar* coprFile = malloc(80 + namelen + auxlen);

memcpy(coprFile, copr.serviceFilename, 5);

coprFile[5] = copr.signPageNumber;

coprFile[6] = copr.authPageNumber;

coprFile[7] = copr.wspcPageNumber;

coprFile[8] = copr.versionNumber;

memcpy(&coprFile[13], copr.bindData, 32);

memcpy(&coprFile[45], copr.bindCode, 7);

memcpy(&coprFile[52], copr.signChlg, 3);

coprFile[55] = namelen;

coprFile[56] = 20; // length of the initial signature

coprFile[57] = auxlen;

memcpy(&coprFile[58], copr.providerName, namelen );

memcpy(&coprFile[58+namelen], copr.initSignature, 20 );

memcpy(&coprFile[78+namelen], copr.auxilliaryData, auxlen );

coprFile[78+namelen+auxlen] = copr.encCode;

coprFile[79+namelen+auxlen] = copr.ds1961Scompatible;

/* Create FileEntry for “COPR.000” file */

FileEntry feCopr;

memcpy(feCopr.Name, “COPR”, 4);

feCopr.Ext = 0;

/* using the 1-Wire file commands in public domain kit, format the device */

int handle, maxwrite;

owFormat(copr.portnum, copr.devAN);

owCreateFile(copr.portnum, copr.devAN, &maxwrite, &handle, &feCopr);

owWriteFile(copr.portnum, copr.devAN, handle, coprFile, 80+namelen+auxlen);

AN156

17 of 23

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.C module, the installation of the secret as well as the creation of an account file

can be done automatically with a single function call. The actual contents of a new certificate file are

written to the device after this step.

Initializing User Tokens with SHADEBIT.C Figure 30

Figure 31 illustrates how the master authentication secret is installed on the user token, as well as the

actual binding of the master authentication secret to produce an authentication secret that is unique to the

user token.

Installing Authentication Secret on DS1963S User Token Figure 31

The final step when initializing a user token is to actually write the account certificate to the data page

where the file was stored. The certificate has an option about whether or not it is signed. If left unsigned,

the 20 bytes of data where the signature would be stored can be used to store any other useful data that

needs to store about the user token. The main situation where there is no need for concern about an

/* Create the empty file on the user token */

FileEntry fe;

memcpy(fe.Name, copr.serviceFilename, 4);

fe.Ext = copr.serviceFilename[4];

owFormat(user.portnum, user.devAN));

owCreateFile(user.portnum, user.devAN, &maxwrite, &handle, &fe));

owCloseFile(user.portnum, user.devAN, handle);

/* File must be created first, so we can get the page number */

user.accountPageNumber = fe.Spage;

/* Install the master authentication secret, same as on the coprocessor */

installSystemSecret18(user.accountPageNumber, inputAuthSecret,

user.accountPageNumber&7);

/* format the bind code properly, for format see AN157 */

uchar fullBindCode[15];

memcpy(fullBindCode, copr.bindCode, 4);

fullBindCode[4] = (uchar)user.accountPageNumber;

memcpy(&fullBindCode[5], user.devAN, 7);

memcpy(&fullBindCode[12], &(copr.bindCode[4]), 3);

/* create the unique secret for iButton */

BindSecretToiButton18(user.portnum, user.accountPageNumber,

user.accountPageNumber&7,

copr.bindData, fullBindCode, TRUE);

/* For DS1963S user tokens */

SHAUser user;

user.portnum = 0;

FindNewSHA(user.portnum, user.devAN, FALSE);

/* Install the authentication secret and write a signed certificate to the device */

InstallServiceData(copr, user, inputAuthSecret, 47);

AN156

18 of 23

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

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 32), which is written to the signing page of the

scratchpad. The rest of the inputs are all stored on the scratchpad of the coprocessor (referred to as the

coprocessor’s “signing scratchpad”). The first parameter stored on the scratchpad is the value of the write

cycle counter for the part (incremented by 1, since the data that it will be verified with is about to be

written). Next is the page number of the user token’s memory pages that will hold the account file. This is

followed by least significant 56 bits of the user token’s address (64-bit Rom ID minus the CRC8). The

last parameter is the 3-byte constant challenge set when the coprocessor was initialized.

Setting up the Coprocessor’s Scratchpad for Data Signing Figure 33

/* 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.initSignature, 20); // Initial Signature

acctData[22] = 0x8B; acctData[23] = 0x48; // Conversion factor (ISO4217)

acctData[24] = 0xE8; acctData[25] = 0x03; acctData[26] = 0; // Account Balance ($10)

acctData[27] = 0; acctData[28] = 0; // TransactionID

acctData[29] = 0x00; // file continuation pointer

acctData[30] = 0x00; accountData[31] = 0x00; // ~CRC16

uchar signScratchpad[32];

int wcc;

/* need to get the value of the write-cycle counter. */

user.writeCycleCounter = ReadAuthPageSHA18(user.portnum, user.accountPageNumber,

user.accountFile.raw, NULL,TRUE);

/* and increment it since we are about to write to the device */

int wcc = user->writeCycleCounter + 1;

/* assign the wcc to the coprocessor’s “signing” scratchpad */

signScratchpad[8] = (wcc&0x0ff);

signScratchpad[9] = ((wcc>>=8)&0x0ff);

signScratchpad[10] = ((wcc>>=8)&0x0ff);

signScratchpad[11] = ((wcc>>=8)&0x0ff);

/* get the page number of the account file and Rom ID of the user token */

signScratchpad[12] = (byte)user.accountPageNumber;

System.arraycopy(owc18.getAddress(),0,signScratchpad, 13, 7);

/* get the signing challenge */

System.arraycopy(signingChlg, 0, signScratchpad, 20, 3);

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+