Exchange Card (eCard) v1.0 SDK
brought to you by Richard King of HAVOC Software
August 5, 1998


     This SDK (Software Developers Kit) comes with the file data structure format, a example
program to read and to write a eCard file with complete source code in Visual basic 5.0 SP3. It
also informs developers of the security options and how to create security eCards. The SDK also
comes with the utility to encrypt the eCard with and to decrypt the eCard. All this will be
explained in this version of the eCard SDK.


SECTIONS

1: File Structure
2: Security Options
3: Description of sample program
4: License





1: FILE STRUCTURE
=================

     The file structure is reported below with the byte index, and the name of sections. The
eCard has two sections. The first one is the version structure which is the WIN32 Type
VS_FIXEDFILEINFO which is 52 bytes. This information can be found in any WIN32 API book.
The second section is the base section. This is the EC_FILE_INFO type which is 1546 bytes, and
the structure is provided below:

EC_FILE_INFO Type table.

Byte Index      Name                      Type + Size in bytes
--------------------------------------------------------------
1-64            eclzGrpName               String | 64 bytes
64-319          eclzGrpComments           String | 255 bytes
319-321         ecblPassword              Boolean | 2 bytes
321-346         eclzPass                  String | 25 bytes
346-396         eclzFirst                 String | 50 bytes
396-446         eclvLast                  String | 50 bytes
446-496         eclvNick                  String | 50 bytes
496-596         eclvEmail                 String | 100 bytes
596-696         eclvURL                   String | 100 bytes
696-721         eclvPhoneHome             String | 25 bytes
721-746         eclvPhoneCellular         String | 25 bytes
746-771         eclvPager                 String | 25 bytes
771-796         eclvFax                   String | 25 bytes
796-896         eclvCompany               String | 100 bytes
896-996         eclvDepartment            String | 100 bytes
996-1021        eclvPhoneWork             String | 25 bytes
1021-1046       eclvPhoneFax              String | 25 bytes
1046-1546       eclvNotes                 String | 500 bytes          


     That is the byte index table for the base of the second structure of the eCard. For the first structure you can get from any WIN32 API book or SDK from Microsoft Corporation web site.

Note:
     ecblPassword is either True or Not True.  This indicates if the security is on or off. True
for on, Not True for off. PLUS the eclzGrpName & eclzFirst must be filled in. And the eclzGrpName can not contain" *.[]`!

The eCard header is:

The dwSignature field is from the first 52 bytes inside the structure type VS_FIXEDFILEINFO
from the WIN32 API. 

     dwSignature = &H48 & &H53 & &H45 & &H43 '=string in ASCII ="HSEC"
     
     If VS_FIXEDFILEINFO.dwSignature = 72836967 Then
          'Format correct version
     Else
          'Incorrect version
     End If  




2: SECURITY OPTIONS:
====================

     The security option is a encryption that ciphers the text so that it is un-readable. eCard
holds a 2 byte section that indicates if the file is encrypted or if it is not. When this 2 byte section returns True then it is wise to prompt the end-user to enter the password, which is used for the key to decipher the eCard. There is an example of this is the example provided in Visual Basic 5.0 inside the eCard SDK.

Pseudo Code Algorithm
---------------------

*This is to show how to check for security options, and what to do in steps

Read eCard
If ecblPassword is True then
     Prompt user for password
          If password equals the eclzPass deciphered with the key password then
               Decipher the rest of the type fields
          else prompt incorrect password: Loop until correct or canceled then end
Load eCard 
  
You must go through this process to check if password is correct. If you do not, the eCard will
load perfectly, but the fields will be un-readable.

NOTE!
     Before encrypting the fields with the tool the SDK gives you, make sure you trim each
field of any empty spaces. This is shown in the example source code.





3: DESCRIPTION OF SAMPLE PROGRAM:
=================================

     The sample program is in Microsoft Visual basic 5.0 with Service Pack 3.0. If you do not
have Visual Basic, you can still view the source by opening the files in notepad.exe. This program is free to modify or compile under your name. This program is 100% freeware.

     The program can be used to study and to use to make sure you have the eCard format
correct if you are converting the eCard function to another language. This program displays how
to use the Security tool to encrypt and decrypt the eCard data when used. This file is called:
spi128.dll. It shows you how to Read the file, Write the format, and a little section to display the information. This program displays all that is needed to use eCard as a export and import file format in your applications. You may copy|paste anything that you like in the files provided.

The Visual Basic project file is called ecardexp.vbp





4: LICENSE
==========

     This format is up for grabs. You may use in any application for nothing, free of charge or
license agreements. Basically this is public domain used by the public for the public. We just want eCard part of the electronic card family. Thank you.






