March
2004, Issue 164
BasicCard
101(Part 1):
Program Your First Smartcard
I’m
assuming that you are going to follow ZeitControl’s
advice and download the latest version of the software
from its web site. When the installation is complete,
a new folder titled “BasicCardPro” will be created below
the C: root. You should plug the CyberMouse reader into
a free COM port on your PC. Keep track of which port
this is because you may need this detail later.
The
CyberMouse gets its operating power by tapping into
either the PS/2 keyboard or PS/2 mouse ports on the
PC. Although there is a green LED on the Cybermouse,
it isn’t a power light; it merely flashes when the PC
is accessing the reader. To ensure that the card reader
is talking to your computer, go to the Tools folder
and run the DOS program Scanrdr.exe. The program should
find your reader and report which COM port it is connected
to.
If
you run this program with a card in place, and request
that it tests the device, the program will do so. More
importantly, it will inform you about what you must
do to ensure that the various DOS/Windows development
programs know which port the reader is attached to.
This is important: the development software supports
virtual card readers, and you want to be sure that you
are actually talking to your CyberMouse when you are
trying to access a real card.
The
first thing I wanted to do was program an empty BasicCard
with one of ZeitControl’s sample programs. Then, I wanted
to see if I could read it using the Balance Reader key
fob. In the Examples/Pocket folder there is a sample
program that basically duplicates the operation of the
preprogrammed demo card (the card with numbers and strings
printed on it). Run the compile.bat program. Watch the
results as this program runs in the DOS window: it should
show no errors and finish off with an indication of
how much of the available EEPROM in the card was used.
This
is where things went off the rails for me. I kept getting
errors, and I could not proceed. I’ll save you some
frustration and point you to the card.prm file in the
Examples folder. Open this with a text editor and go
through the list of the BasicCard variants. All but
one of the variants are commented out. Make sure the
active one corresponds to the card you are using (a
ZC3.7 or 3.9), and then edit the file to match your
card. Also, make sure that the compile.bat file contains
the following text:
..\..\zcmbasic
-OI
@..\card.prm prcard
-I..\..\Inc
The
compile.bat file, as installed from ZeitControl’s web
site, was different and did not generate an image file.
The significance of all of these command line switches
is explained in the manual—but, at this early stage,
you haven’t read the entire manual, have you?
Assuming
that you have managed to compile the program successfully,
you should see the prcard.img card-image file in the
Pocket folder. This is the binary image of the code
that must be downloaded into the BasicCard. Run the
download.bat command, which is also found in the Pocket
folder, and watch the DOS window for messages as the
programming proceeds. The final message should be
“SET STATE TEST.” Now that you have programmed
your first card, place it in the little Balance Reader.
It should display the same series of strings and numbers
that are printed on the preprogrammed test card.
BasicCard/PC
APPLICATION
The
next logical step is to load a BasicCard with an application
that operates in conjunction with your PC/CyberMouse
card reader. ZeitControl provides a couple of samples,
including a debit card application and a calculator
application.
The
debit card application demonstrates, among other things,
the encryption routines. The calculator application
demonstrates the floating-point match routines in the
BasicCard. In both cases, these applications split up
the actual task between the PC host and the BasicCard.
The calculator program is strictly a demo, and it doesn’t
serve a useful purpose in the real world. However, the
debit card program actually performs substantially the
same function as a real debit card would (i.e., the
PC runs a program that initializes the BasicCard for
a particular name/PIN number and then preloads it with
the desired amount of credit). The BasicCard itself
stores this information in its nonvolatile EEPROM memory,
which is only readable and alterable when connected
to a reader implementing the proper encryption routine/key
value. Then, another PC (or POS terminal), which is
running a “dealer|” program, has the ability to subtract
amounts from the remaining balance in the card (i.e.,
debit it) until the card is used up, so to speak.
To
try this application, you should follow the same procedure
outlined for the Balance Reader sample. However, you
must open the Debit folder and run the compile.bat and
download.bat programs. The same two warnings I mentioned
before also apply here, except that the change involving
the card.prm file applies globally to all sample programs
contained in the Examples folder. Chances are, you already
have looked after this concern.
With
the debit program downloaded on the card, you now have
to run the part of the application that runs on the
PC. ZeitControl calls all programs that run on the host
“terminal” programs. I expect that comes from
the concept that the BasicCard is running the guts of
the program, and the PC is acting as a “terminal”—from
the old days of computing, when the operator used a
terminal and the mainframe computer was elsewhere.
As
part of the compilation, Dealer.exe and Issuer.exe files
are generated. You can run the DOS issuer program to
initialize the card—or to personalize it, as ZeitControl
calls the process. Assuming you have the newly programmed
BasicCard still in the reader, you should be able to
complete this procedure successfully. You can then run
the Dealer.exe program to debit amounts from the card
after you have correctly entered the PIN number.
Using
either ZeitControl’s zcpde.exe program, which is basically
just a Windows-based text editor, or any other text
editor, you can examine or modify Dealer.bas or Issuer.bas
to see exactly how ZeitControl’s Basic language works.
You’ll note that these listings depend heavily on Include
files for many definitions. I found it useful to print
these common Include files because it made understanding
the code somewhat easier.
You
will notice that the interaction between the terminal
program and the BasicCard program is done using commands.
These command definitions contain the actual token that
is sent by the terminal program and parsed by BasicCard’s
interpreter for any given command. Following the ISO
7816 standard, the tokens actually consist of two bytes:
a class (CLA) byte and an instruction (INS) byte. Some
tokens are reserved for a few predefined functions that
exist in all BasicCards and shouldn’t be used for your
own functions.
In
addition to specifying these tokens, the command definition
also includes the exact format of any parameters that
are passed between the terminal program and the BasicCard
program. If you are familiar with the different ways
of passing parameters to functions and subroutines (by
reference, by value) should note that these conventions
are somewhat different in this unique programming environment.
This is well documented in the manual.
As
I alluded to before, the program running in the BasicCard
is basically a group of functions that are triggered
by the receipt of command tokens from the device to
which it is connected. The BasicCard program likely
also contains initialization code that runs when the
card is inserted into a reader; however, by and large,
it is a slave device. A BasicCard program therefore
looks a bit strange in that it doesn’t contain what
you would normally call the “mainline” code. That part
of the application resides in the terminal program running
in the external device.
