Jaccal overview

Jaccal is a smart card access API. Its original intentions are to allow Java developers who are not familiar with smart card technology to have a simple access to smart cards. However we have also wrapped a scripting engine around Jaccal to enable fast prototyping and execution of smart card commands. This can help smart card professionals to perform card validation and allow normal users to extract useful information from the card, without heavy programming.

What's in Jaccal

In the current Win32 binary release of Jaccal (there is no source release, you have to get it from the CVS yourself), you will find 2 Windows executables, 3 Java jar archives and 1 Windows dll:

1. anubis.exe - this is the Anubis Smart Card Script Editor executable
2. jaccal.exe - this is the Jaccal console executable
3. jaccal-core.jar - this is the core library for accessing smart cards
4. jaccal-anubis.jar - this is the library for running Anubis and the Jaccal console
5. jaccal-pcsc.dll - this is the dynamic link library that bridges Jaccal with PCSC (Personal Computer/Smart Card interface)

You will also find an examples directory with a number of sample scripts you can try on your smart card.

The Windows executables are wrappers created by JSmooth. Jaccal uses its own PCSC bridge to access the Windows PCSC implementation. For advanced developers, you can try to use another technology to access the smart card by extending the SessionFactory and Session classes, and configuring the jaccal.properties configuration file in jaccal-core.jar.

How to use Jaccal

All the binary release files need to be in the same directory. To run anubis, just double click on the anubis.exe file. Anubis provides a GUI for users to enter the scripts and execute them. The GUI is intuitive.

You can also use Jaccal from the console with this command:

	        jaccal -f sample_script.bsh
	      

This will execute the given script.
The -s flag takes in a script string as a parameter and executes it.

	        jaccal -s "anubis.open(); .... anubis.close();"
	      

The output and the error goes to the system output and system error respectively. If you have not piped them anywhere they will go to the console screen.

Embedding Jaccal in UltraEdit

Jaccal console is ideal for embedding into your favorite IDE/text editor. The following are instructions to embed Jaccal in a typical IDE/text editor (UltraEdit). UltraEdit is a powerful and popular commercial text editor. UltraEdit is not affliated with Jaccal or the authors.

Jaccal is embedded in UltraEdit through the customizable user tools:

1. Click on 'Advanced\Tool Configuration' from the menu
2. Browse the command to where jaccal.exe is Add in the -f flag to read from a source script and the %F parameter to take from your currently opened file. Your command should be something like this

                 D:\projects\jaccal\exe\jaccal.exe -f %F
                 

3. Set the working directory to where you found jaccal.exe. This is important as Jaccal looks for the libraries beginning from here
4. Chose a name for your menu item
5. Select 'Save Active File' to save the script file before it is executed
6. Optionally you can also set the icon for the menu item from 'Advanced'
7. On the Command Output radio boxes, choose 'Output to List Box'
8. Then select the 'Capture Output' checkbox

To execute a script file, open it normally using UltraEdit. Then select 'Advanced' from the menu and select the newly created user tool. An output box will appear containing the output of the execution.

You can also add in syntax highlighting to the script files. Just add in this wordfile to the end of the existing one, modifying it as necessary.

Embedding Jaccal in Crimson Editor

The following are instructions to embed Jaccal in Crimson Editor. Crimson Editor is a freeware source code editor in Windows. It is not open source. Crimson Editor is not affliated with Jaccal or the authors.

Jaccal is embedded in Crimson Editor through the customizable user tools, very much similar to UltraEdit above:

1. Click on 'Tools\Conf. User Tools ...' from the menu
2. Fill in the menu text with any name (e.g. jaccal)
3. Browse the command to where jaccal.exe Your command should be something like this

                 D:\projects\jaccal\exe\jaccal.exe 
                 

4. Under the 'Argument' text box, enter this:

                 -f $(FileDir)\$(FileName)
                 

5. Set the initial directory to where you found jaccal.exe. This is important as Jaccal looks for the libraries beginning from here
6. Select 'Save before execute' to save the script file before it is executed
7. Select the 'Capture Output' checkbox

To execute a script file, open it normally using Crimson Editor. Then select 'Tools' from the menu and select the newly created user tool. An output box will appear containing the output of the execution.

Further questions?

Please browse through the forums or join the mailing list.