{
Symbol file for the 'Dallas Primary' group (U.S./Canada version).

Ver 1.00 : Initial symbol file creation
3/11/97

--------------------------------------------------------------------------------------------------------------------------------

{

Group file for the 'Dallas Primary' Transaction Group (U.S./Canada version).
Ver 1.00 : Initial group file creation
3/11/97

The Dallas Semiconductor Primary Group contains 4 primary scripts and their supporting data objects. Three of the scripts (documented below) provide RSA encryption/decryption capability. The fourth script is used for signature generation.

Begin

Open:

Input1: InputData;
OutExp: Exponent;
OutMod: Modulus;

Locked:


CiBPublicExp: Exponent;
CiBModulus: Modulus;
SignCount: Counter;
TimeStamp: ClockOffset;
RegNumber: ROMData;
GpInfo,
GpCertificate: Configuration;
Output1, Output2: OutputData;

EncryptCiBKey,
DecryptCiBKey,
EncryptOutKey,
SignCiBKey: Script;

Private:


CiBPrivateExp: Exponent;
Padding: RandomFill;

End

Script EncryptCiBKey;
{

Encrypt data supplied in the input object using the Crypto iButton™'s public key.

Output1 := Input1 ^ CiBPublicExp Mod CiBModulus;

Script DecryptCiBKey;
{

Decrypt data supplied in the input object using the Crypto iButton's private key.

Output1 := Input1 ^ CiBPrivateExp Mod CiBModulus;

Script EncryptOutKey;
{

This script simply provides easy access to the Crypto iButton's co-processor, allowing the user to perform an arbitrary modular exponentiation.

Output1 := Input1 ^ OutExp Mod OutMod;

Script SignCiBKey;
{

Sign data supplied in Input1. This script appends the value of SignCount, RegNumber, and TimeStamp to Input1. The result of these concatenations is placed in Output1. Output1 is then hashed using SHA-1. Random data is appended to the hash value and the result is signed with the Crypto iButton's private key. The resulting signature is placed in Output2.

Output1 := Input1 & SignCount & RegNumber & TimeStamp;
Output2 := (SHA1(Output1) & Padding) ^ CiBPrivateExp Mod CiBModulus;

{

Symbol file for the 'Dallas Primary' group (export version).

Ver 1.00 : Initial symbol file creation
3/11/97

--------------------------------------------------------------------------------------------------------------------------------

{

Group file for the 'Dallas Primary' Transaction Group (export version).
Ver 1.00 : Initial group file creation
3/11/97

The Dallas Semiconductor Primary Group contains one primary script and its supporting data objects. This script is used for signature generation.

Begin

Open:

Input1: InputData;

Locked:


CiBPublicExp: Exponent;
CiBModulus: Modulus;
SignCount: Counter;
TimeStamp: ClockOffset;
RegNumber: ROMData;
GpInfo,
GpCertificate: Configuration;
Output1, Output2: OutputData;

SignCiBKey: Script;

Private:

CiBPrivateExp: Exponent;
Padding: RandomFill;

Script SignCiBKey;
{

Sign data supplied in Input1. This script appends the value of SignCount, RegNumber, and TimeStamp to Input1. The result of these concatenations is placed in Output1. Output1 is then hashed using SHA-1. Random data is appended to the hash value and the result is signed with the Crypto iButton's private key. The resulting signature is placed in Output2.

Output1 := Input1 & SignCount & RegNumber & TimeStamp;
Output2 := (SHA1(Output1) & Padding) ^ CiBPrivateExp Mod CiBModulus;

The Crypto iButton API function calls that are required to communicate with the Crypto iButton to perform the digital signature operation are outlined below:

1. Import Constant Values from the Symbol File

The Symbol File should be imported into the source code so that the symbolic names can be used instead of the more obscure object numbers:

Const

CiBPublicExp	= 1; { User Objects }
CiBModulus	= 2;
CiBPrivateExp	= 3;
Input1	= 4;
SignCount	= 5;
TimeStamp	= 6;
SignCiBKey	= 7;
GpInfo	= 8;
GpCertificate	= 9;
OutExp	= 10; { U.S./Canada Version Objects }
OutMod	= 11;
EncryptCiBKey	= 12;
DecryptCiBKey	= 13;
EncryptOutKey	= 14;
Output1	= 160; { Auto objects used by Dallas Primary }
Output2	= 161;
RegNumber	= 163;
Padding	= 164;

2. Provide Function Prototypes for the Required API Calls

Function FindCiBs(P: Pointer): Pointer;
StdCall; External 'CIBAPI.DLL';

Function SelectCiB(P: Pointer): Boolean;
StdCall; External 'CIBAPI.DLL';

Function GetGroupID(lpGroupName, lpGroupID, lpRP: Pointer): Boolean;
StdCall; External 'CIBAPI.DLL';

Function ReadCiBObject(GroupID: Byte; lpGroupPIN: Pointer; ObjectID: Byte;
lpObject, lpRP: Pointer): Boolean; StdCall; External 'CIBAPI.DLL';

Function WriteCiBObject(GroupID: Byte; lpGroupPIN: Pointer; ObjectID: Byte;
lpObject, lpRP: Pointer): Boolean; StdCall; External 'CIBAPI.DLL';

Function InvokeScript(GroupID: Byte; lpGroupPIN: Pointer; ObjectID: Byte;
RunTime: Word; lpRP: Pointer): Boolean; StdCall; External 'CIBAPI.DLL';

Function GetCiBError: Word; StdCall; External 'CIBAPI.DLL';

3. Declare Constants, Types, and Variables

Const

MaxPINLen	= 8;
MaxNameLen	= 16;
MaxPacketLen	= 128;
MaxObjLen	= 128;
Name : String	= 'Dallas Primary'; { Dallas Semiconductor Primary Group }
LargeKeyTime	= 1500; { Estimated time parameter for large key encryption }
SmallKeyTime	= 250; { Estimated time parameter for small key encryption }

Type


TGroupPIN = Record

Len : Byte;
PINData : Array[1..MaxPINLen] of Byte;
End;
PGroupPin = ^TGroupPin;

TGroupName = Record


Len : Byte;
NameData : Array[1..MaxNameLen] of Byte;
End;
PGroupName = ^TGroupName;

TCiBObj = Record


Attr, OType, Len : Byte;
ObjData : Array[1..MaxObjLen] of Byte;
End;
PCiBObj = ^TCiBObj;

TRetPacket = Record


CSB, GroupID, DataLen : Byte;
CmdData : Array[1..MaxPacketLen] of Byte;
End;
PRetPacket = ^TRetPacket;

Var


lpGroupPin	: PGroupPin;
lpGroupName	: PGroupName;
lpObject	: PCiBObj;
lpRP	: PRetPacket;
GroupPin	: TGroupPin;
GroupName	: TGroupName;
CiBObject	: TCiBObj;
CiBRP	: TRetPacket;
GroupID	: Byte;

4. Initialize Data Structures

Procedure Initialize;

Begin

lpGroupPin	:= @GroupPin;
lpGroupName	:= @GroupName;
lpObject	:= @CiBObject;
lpRP	:= @CiBRP;

With GroupName do Begin

Len := Length(Name);
For I := 1 to Len do NameData[I] := Byte(Name[I]);
End;
GroupPin.Len := 0;
End;

5. Establish a Communication Link to the Crypto iButton

For example, a function such as the one below can be used to identify and link to the first Crypto iButton found on the 1-Wire bus:

Function AttachCiB: Boolean;
{

This function uses FindCiBs and SelectCiB to establish a connection to the first Crypto iButton on the 1-Wire bus. It returns True if the attachment was successful and the device contains a group named 'Dallas Primary', otherwise it returns False.
}

Var



RomPoint : Pointer;
CiBCount : Word;

Begin


CiBCount := 0;
RomPoint := FindCiBs(@CiBCount);
AttachCiB := (RomPoint <> Nil) and (CiBCount > 0) and SelectCiB(RomPoint)
and GetGroupID(lpGroupName, @GroupID, lpRP);
End;

6. Transmit the Data to be Signed to the Crypto iButton

First put the data to be signed in the structure pointed to by lpObject, then execute a command of the form:

F := WriteCiBObject(GroupID, lpGroupPin, Input1, lpObject, lpRP);

(Note that if there is a Group PIN, the structure pointed to by lpGroupPin must contain the PIN. If there is no group PIN, the Len parameter of the GroupPin structure must be zero.)

If F returns True, the operation was successful, otherwise call the GetCiBError API function to determine the type of error that has occurred. Values returned by GetCiBError and their meanings are given in the Cryptographic iButton Firmware Reference Manual. Two particular errors that should be considered are ERR_BAD_GROUP_PIN = $82 and ERR_INACTIVE = $D1. The first error occurs when the part expects a PIN but the value of the PIN specified in the GroupPIN variable is missing or incorrect. The second error occurs if the activation of the Crypto iButton has expired and the device requires reactivation from the Dallas Semiconductor activation website.

7. Execute the Signature Script

Now that the data to be signed has been written into the input object designated by Input1, the signature script can be executed by calling the InvokeScript API function:

F := InvokeScript(GroupID, lpGroupPin, SignCiBKey, LargeKeyTime, lpRP);

Note that the value of the estimated time parameter LargeKeyTime given in Step 3 above is based on an RSA key length of 1024 bits. If the key length is less than this value, a smaller value of LargeKeyTime may be used. (The SmallKeyTime value is used when encrypting or verifying a digital signature with a small public exponent, such as 65537.)

If the function returns True, the operation was successful, otherwise call the GetCiBError API function to determine the type of error that has occurred. On successful completion, the script leaves the results of the digital signature calculation in the output objects Output1 and Output2.

8. Read Back the Two Components of the Completed Digital Signature

The digital signature has two components that must be read back from the Crypto iButton. Object1 contains the exact data to be "signed" to create the digital signature or response to a challenge. This data must be collected from the Crypto iButton and supplied as a part of the digital signature. It contains the timestamp, the unique lasered registration number of the Crypto iButton, the unique transaction counter number, and the challenge or message digest. The function to read this data structure is called as follows:

F := ReadCiBObject(GroupID, lpGroupPin, Output1, lpObject, lpRP);

Again, the function returns True if it was successful. The data is returned through the pointer lpObject. To create the digital signature, the Crypto iButton appended a packet of random fill to this data to make it one bit shorter than the modulus. Then it was signed by exponentiating it with the private key. The following function call returns the result of this operation:

F := ReadCiBObject(GroupID, lpGroupPin, Output2, lpObject, lpRP);

If it returns True, the data is returned through the pointer lpObject. The response to a challenge requires that both the data from Output1 and the data from Output2 be returned to the remote party who provided the challenge. For a digital signature, both the contents of Object1 and the contents of Object2 must be appended to the original document to form the digital signature.

Note that because of the random fill, every digital signature and response to a challenge is different, even if the message digest or challenge is the same. This feature helps to defeat certain kinds of attacks on the security of the Crypto iButton.

The Crypto iButton API function calls that are required to communicate with the Crypto iButton to perform the encryption and decryption operations are outlined below:

1. Perform Steps 1 through 5 described in Appendix C above to set up the environment and prepare the Crypto iButton for use.

2. EncryptOutKey

To use this script, the intended recipient's public key must first be loaded into OutExp and OutMod, and the random session key must be loaded into Input1. Then the EncryptOutKey script must be executed, and the result retrieved from Output1:

a. Load the Exponent

First put the RSA exponent of the intended recipient's key into the variable pointed to by lpObject, then execute the API function:

F := WriteCiBObject(GroupID, lpGroupPIN, OutExp, lpObject, lpRP);

If the function returns True, the exponent has been written successfully into OutExp.

b. Load the Modulus

First put the RSA modulus of the intended recipient's key into the variable pointed to by lpObject, then execute the API function:

F := WriteCiBObject(GroupID, lpGroupPIN, OutMod, lpObject, lpRP);

If the function returns True, the modulus has been written successfully into OutMod.

c. Load the Session Key

First put the session key used for encrypting the message into the variable pointed to by lpObject, then execute the API function:

F := WriteCiBObject(GroupID, lpGroupPIN, Input1, lpObject, lpRP);

If the function returns True, the session key has been written successfully into Input1.

d. Invoke the Script

F := InvokeScript(GroupID, lpGroupPin, EncryptOutKey, SmallKeyTime, lpRP);

If the function returns True, the encryption has been performed successfully and the result is waiting for retrieval in Output1. Note that the use of the SmallKeyTime parameter is justified if the public exponent supplied in step 2.a. above is small. A full-length exponent requires use of LargeKeyTime.

e. Retrieve the Result

F := ReadCiBObject(GroupID, lpGroupPin, Output1, lpObject, lpRP);

If the function returns True, the session key encrypted with the intended recipient's public key is available in the variable pointed to by lpObject.