This document is intended to answer the most common questions developers ask about the Dallas Semiconductor's Developer's Kit for our JavaTM Powered Crypto iButtonsTM (a.k.a.: iB-IDE). If you have a question which is not answered here, please post your question to the Java Powered iButton Forum at java-powered-ibutton@ibutton.com. If you do not subscribe to this list, you can do so by sending an E-mail to java-powered-ibutton-request@dalsemi.com with subscribe java-powered-ibutton in the body of the message. This list is monitored by interested developers and Dallas Semiconductor engineers.
The FAQ relating to iB-IDE version 1.1 is also still available.
Questions from Developers
Dallas Semiconductor Support Team Answers
JiBMultiFactory is now shared between
OneWireMonitor, which listens for iButtons to be
inserted and removed, and OneWireContainer16, which
performs APDU communications with the Java Powered iButton.
Answer:
The DS Java-Powered Crypto iButton is a secure
Java Virtual Machine encased in a stainless-steel
circular container only 16mm wide. It is Java-powered and
designed according to Sun's Java Card 2.0 specification.
Because it has more RAM than other Java Card-based
products, your programs can do more, and since it relies
on battery-backed static RAM to store its applets, it can
be programmed over and over again as needs change.
Perhaps best of all, the iButton's small size
means it can be integrated into all sorts of personal
accessories for both safe keeping and convenience of
use. Find out more at http://www.ibutton.com/store/index.html.
This iButton has a super-fast, 1024-bit modular math coprocessor for cryptographic operations. This is, in fact, the same coprocessor already proven in the DS Crypto iButton with Dallas O/S. Having such a coprocessor makes the Java Powered Crypto iButton ideal as a general-purpose security device, fully capable of performing secure transactions over the internet.
Answer:
This version was developed and tested for on JDK 1.2
and JDK 1.3. This is a requirement to
install and run iB-IDE, but the underlying iButton
code needed to simply run iButton applications
will work on JDK 1.1.x.
This version fixes the previous problems where no JDK
other than 1.2.1 and 1.2 would work with the iB-IDE.
Future versions of the JDK should be compatible with
iB-IDE, but as long-time users know, problems may arise
from future JDK releases.
Answer:
The iB-IDE supports Windows 9xTM,
Windows NT/2000TM,
SolarisTM versions 2.5.1
or greater, and Linux.
Answer:
Try passing a command line parameter to the application
that you are running. The command line parameter is the
communications port name on your machine. Example:
"java BusinessCardDisplay COM1"
Answer:
In order to have "permission" from Windows NT
to install drivers, you must be using an
Administrator account when you install iB-IDE. Also,
please note that in order for the NT drivers to work
properly, you must also have Service Pack 2 or greater
installed on your machine.
NOTE: These drivers are only needed if you are using the DS1410E parallel port adapter. They should not be needed for serial port communication, since serial communication can be achieved using pure Java with the Java COMM API.
Answer:
What you see are debug and test statements sent to the
console screen used during development. This, in itself,
is not a cause for worry. If your applet still finds the iButton,
then these messages may be ignored. If not, first make
sure that there are no other applications running that
may be using this port. If all else fails, move your Blue
Dot adapter to another port.
Answer:
The most likely cause is that Java cannot find a native
library it needs in order to continue executing. If you
are on Windows 95 or NT, make sure that both the
ibtmjava.dll (iButtonLegacy.dll for old iB-IDE 1.1x code) and
win32com.dll are in the
[JDK_ROOT]\jre\bin directory. If you are
running Unix, then make sure the appropriate libraries
can be found in the directory pointed to by the
environment variable LD_LIBRARY_PATH.
This problem is also seen while using early betas of JDK 1.2. We currently recommend using the release version of JDK 1.2 or later.
You might also see this sort of problem if you are running a vendor's VM other than the one provided by Sun. While several other vendors VM's have been shown to work well with these libraries, you should check with your vendor to find out whether their VM's are conformant to regular native Java standards, including where the appropriate libraries should reside.
Answer:
You can order directly from our Information
Security Store or contact Brian Kraman via e-mail at brian.kraman@dalsemi.com
for purchasing information.
Answer:
A return code of 0x6681 indicates a security problem
while attempting to perform a command function, such as
running an applet. All iButtons for Java have
potential to be locked using password protection. The
rings from JavaOne 1998 use the PIN "1!J1".
Answer:
A return code of 0x6903 is very similar to the above code
of 0x6681, except that this code occurs as a result of attempting
to load an applet. It also indicates that the master
password supplied is incorrect. The only password used on
Java Powered iButtons supplied at Java One 1998 is
"1!J1".
Answer:
A return code of 0x6902 (Bad API Version) means that you
have tried to load an applet on your iButton that
was built for a different iButton version. To fix
this, determine the firmware version string of your Java
Powered iButton using
APDUSender. Then, under COMPILE | OPTIONS, choose the
correct Target iButton Version.
Answer:
This error indicates that once the applet was loaded,
there was a problem calling the install() method.
This can be because an applet was written for the
JavaCard 2.1 specification, while the iButton
only supports the JavaCard 2.0 specification. This error
can also appear if your applet is using an Abstract or
Heirarchichal structure, where your applet either implements
some interface or extends a class that extends a class.
Such a scheme is legal, but you must use the '-a' option
to identify the main applet class (BuildJiBlet versions 0.59
and later).
Answer:
This error (Class Length Overrun) can occur when
you are trying to load a larger applet onto the
Java Powered iButton. The applet must be
sent in packets, and transmission errors can cause
this failure. You can increase the packet size to
reduce the occurance of this error. In your code,
add the line
owc16.setLoadPacketSize(112);owc16
is a com.dalsemi.onewire.container.OneWireContainer16 object).
The default Load Packet Size is 64. You should not
go above 112 or below 64.
Answer:
This can occur when compiling applets for the Java Powered
iButton using JDK version 1.3. We have not determined
the exact cause yet, but believe it has something to do with
the JDK changing the way it handles static initializers. If you
encounter this error, we recommend you change to use JDK1.2,
at least for building your applets.
Answer:
A return code of 0x8453 is caused by selecting an applet
that does not exist on the Java Ring. This almost always
occurs when a developer believes an applet has been
loaded, but for some reason it has not.
Answer:
This usually happens when the applet has failed to
load or has not been selected before communication,
so the Java iButton does not know what to do
with your APDU. Make sure to select the
applet before you communicate with it.
Answer:
A 0x6F00 means "Uncaught Exception". Either
an exception
was thrown from the iButton and
there was no try | catch block around it
(like a NullPointerException) or an error was thrown
that could not be 'caught' (like an OutOfMemory Error).
To determine what happened, you can use APDU Sender
and issue the command Get Last Error or in your
code you can do something like the following:
if (statusWord==(short)0x6f00)
try
{
//owc16 is a OneWireContainer16 object
ResponseAPDU response = owc16.getLastError();
int err = 0x0ff & response.getBytes()[0];
System.out.print("Last Error reported as 0x");
if (err<16) System.out.print('0');
System.out.println(Integer.toHexString(err));
}
catch(Exception e)
{
System.out.println("Could not getLastError!");
}
You can determine the meaning of the returned code from the
Status Word document. Make sure
you know the firmware version of your iButton to determine
the meaning of an exception.
Answer:
Make sure that both types of garbage collection are enabled.
You can do this with the APDU
Sender program (press F4 to start it). There are two types
of garbage collection: Applet and Ephemeral. Under APDU Sender,
there are Get and Set commands for both types. Make sure the
Get methods return 1.
Note that unlike on a PC or workstation, garbage collection in
the iButton will not begin until the process
method returns. Variables may fall out of scope, but they will
not be available for collection until the end of the process
method.
Answer:
You probably have environment size problems. You can
change this value in Windows 95 by pulling up properties
on the DOS shell you are using. Under the Memory tab,
change the Initial Environment Size to a larger value.
Apply the changes, and try again.
A similar error, "NoClassDefFoundError" may occur on the Windows 95 platforms for unknown reasons, and may sometimes be corrected by either (A) using the syntax "java -classpath %classpath% <myApplet>", or (B) by changing the order of required jar files in the classpath so that the jar file used by the application for itself is last.
Answer:
There is a bug in the Java One '98 release of the iButton
for Java which prevents the array index parameter to
"sendBytesLong()" from completing successfully.
This can be worked around by sending arrays which are
larger than 255 bytes in pieces. By iteratively sending
smaller packets, you can successfully load an array which
is larger than 255 bytes. (The code generated by iB-IDE
will automatically handle this for you.) This has been
fixed in the 1.0 release of the Java-Powered iButton.
If you are
using the OpenCard API in your code, these
classes are a product of the
OpenCard consortium and the latest documentation can be
downloaded from the associated web site. The 1-Wire API
package has its own version of CommandAPDU
and ResponseAPDU. Documentation for these
is available through iB-IDE's Help menu and with
the 1-Wire API download, available at
ftp://ftp.dalsemi.com/pub/auto_id/public/.
Answer:
For information on the latest Java Card specification refer
to
http://www.javasoft.com/products/javacard/index.html.
However, the Java Powered iButton conforms to the
Java Card 2.0 specification. Documentation is hidden on
Sun's website but can still be found at
http://www.javasoft.com/products/javacard/javacard20.html#download.
For the latest in OpenCard technology, visit http://www.opencard.org.
Check http://www.ibutton.com/iB-IDE for updated documentation on the iB-IDE.
Answer:
This is an easy problem to fix, once you realize what
causes it. The "javax.comm" package changed
slightly when Sun promoted the code from EA to Beta
status. In doing so, two method names have been changed:
openPort() & closePort(). The new names for these
methods is simply open() & close(). The latest
version is included with the installation for iB-IDE.
The latest and most current version of our developer's kit is iB-IDE version 2.0. We strongly encourage all our developers to make the transition to this version if they are currently working with older versions.
What are the different versions of the iButton,
and what cryptographic functions are available on each?
Answer:
The version 0 iButtons - a.k.a. 1998 JavaOne iButtons
- (Java iButton Firmware Version 0.03.0003) have no
modular exponentiation capabilities. This ring is
therefore not export controlled. It does have a SHA-1
hash class (javacardx.crypto.Sha1MessageDigest) and a
random number generator (javacardx.crypto.Random).
The 1.0 iButtons (Java iButton Firware Versions
1.00.0004, 1.01.0004, 1.02.0005, and 1.03.0005) have
a modular exponentiation function in
addition to the version 0 iButton functions. This
new function can be found in the
com.dalsemi.system.Coprocessor class. This allows any
modular exponentiation based cryptography schemes (RSA,
DSA, etc.) to be implemented on the iButton. (See
the RSASign example project in iB-IDE).
The 1.1 iButtons (Java iButton Firmware Versions
1.10.0006 and 1.11.0006) have the javacardx.crypto package fully
implemented (providing DES, RSA implementations). See the
javacardx.crypto specification for the available
functions.
The 2.2 iButtons (Java iButton Firmware Versions
2.2.0007) have 134K memory and support RSA keyset
generation through a Dallas Semiconductor provided class.
How can I build Java
Powered iButton applets outside of the iB-IDE?
Answer:
Building a Java Powered iButton applet outside of the iB-IDE is a two step process. First you must compile the applet into a class file (or files), then you must build a .jib file from the class file(s).
Compiling:javac -bootclasspath "d:\iBIDE\class\iButtonXX.jar;C:\Program
Files\JavaSoft\JRE\1.2\lib\rt.jar" mysource.javajava -classpath c:\jdk1.2.1\jre\lib\ext\jib.jar;%classpath% BuildJiBlet -f mysource.class
-o mysource.jib -d jibXX.jibdbjavac -bootclasspath "d:\iBIDE\class\iButtonXX.jar;C:\Program
Files\JavaSoft\JRE\1.2\lib\rt.jar" mysource.java myobject.javajava -classpath c:\jdk1.2.1\jre\lib\ext\jib.jar;%classpath% BuildJiBlet -f build
-o mysource.jib -d jibXX.jibdbHow can I build and run the host
applications that talk to the Java Powered iButton
from outside of the iB-IDE?
Answer:
You will need to include the following files in your classpath:
set classpath=.;c:\jdk1.2.1\jre\lib\ext\base-core.jar;c:\jdk1.2.1\jre\lib\ext\base-opt.jar;c:\jdk1.2.1\jre\lib\ext\comm.jar;c:\jdk1.2.1\lib\ext\OneWire.jarjavac -classpath .;c:\jdk1.2.1\jre\lib\ext\base-core.jar;c:\jdk1.2.1\jre\lib\ext\base-opt.jar;c:\jdk1.2.1\jre\lib\ext\comm.jar;c:\jdk1.2.1\lib\ext\OneWire.jar myHostSource.javajava -classpath .;c:\jdk1.2.1\jre\lib\ext\base-core.jar;c:\jdk1.2.1\jre\lib\ext\base-opt.jar;c:\jdk1.2.1\jre\lib\ext\comm.jar;c:\jdk1.2.1\lib\ext\OneWire.jar myHostSource java -classpath .;c:\jdk1.2.1\jre\lib\ext\OneWireAPI.jar myHostSourceIf you are using the OpenCard API, you must also have the file opencard.properties in your [jdk]\jre\lib directory. If you are using the 1-Wire API, the onewire.properties file must be in the same location. These files select which port you are going to use for communication with the iButton. See the discussion on OpenCardPropertyLoadingException for more details on this file, or visit the OpenCard website. For more on the onewire.properties file, see the 1-Wire API discussion.
Answer:
The program is trying to find the file opencard.properties on your system to
determine which port it should use to communicate with the iButtons. It should
be located in your [jdk]\jre\lib directory. The contents
the file should look something like this (on a Windows machine):
#Only the last uncommented line will be used to search for iButtons.
#Uncomment the next line to search COM1 using native code
#OpenCard.terminals=com.dalsemi.onewire.jib.terminal.JiBCardTerminalFactory|OneWireAdapter|ONEWIRE_PORT_TYPE_LEGACY_SERIAL|COM1
#Uncomment the next line to search COM1 using pure java code
OpenCard.terminals=com.dalsemi.onewire.jib.terminal.JiBCardTerminalFactory|OneWireAdapter|ONEWIRE_PORT_TYPE_SERIAL|COM1
#Uncomment the next line to search COM2 using native code
#OpenCard.terminals=com.dalsemi.onewire.jib.terminal.JiBCardTerminalFactory|OneWireAdapter|ONEWIRE_PORT_TYPE_LEGACY_SERIAL|COM2
#This line will search the LPT1 for iButtons.
#OpenCard.terminals=com.dalsemi.onewire.jib.terminal.JiBCardTerminalFactory|OneWireAdapter|ONEWIRE_PORT_TYPE_LEGACY_PARALLEL|LPT1
#Uncomment the next line to search LPT2 using native code
#OpenCard.terminals=com.dalsemi.onewire.jib.terminal.JiBCardTerminalFactory|OneWireAdapter|ONEWIRE_PORT_TYPE_LEGACY_PARALLEL|LPT2
Note that previous versions of the Java iButton API used lines like the following their opencard files:
OpenCard.terminals=com.ibutton.oc.terminal.jib.iButtonCardTerminalFactory|iButtonAdapter|iBUTTON_PORT_TYPE_LEGACY_SERIAL|COM1
If you continue to have problems with this exception, you might also try
copying the opencard.properties file into your working directory.
Answer:
Only the most recent version (2.2) of the Java Powered iButton
can generate an RSA keyset. This functionality is available in the
com.dalsemi.security.RSAKeyGenerator class.
Previous versions of the iButton that support RSA operations must have
their keysets generated outside the iButton, then loaded into
the iButton. Note that some keyset generation programs (including
any code in Java that uses the BigInteger class to create primes)
can sometimes create what appears to be a prime of N+1 bytes instead of the
requested N bytes (for instance, your prime will be 129 bytes instead of 128).
In most cases, this extra byte is a leading zero attached to ensure the prime
is not interpreted as a negative number. You can usually truncate this leading
byte.
Answer:
Yes! Previous versions of the iB-IDE used older
native libraries that conformed to the stubs interface,
not supported by HotSpot and only supported in the JDK
through the use of the -classic switch.
However, since the Java Powered iButton API has
been rewritten to be a part of the 1-Wire API, the native
libraries now conform to the JNI interface, meaning they
will work with HotSpot, and will work without the
-classic switch.
Answer:
This is caused by [jdk1.2]\bin not being in your PATH
environment variable. Add this to your PATH (making
sure it is the first Java VM bin directory in your PATH).
Windows systems may need to reboot.
You can also go into Compile -> Options and put the full path to javac.
Answer:
Unix users can choose to specify the path to the desired
VM if it doesn't appear in the available list. Java
InstallShield will search the PATH for available VM's, so
adding the desired VM bin directory to the PATH (as the
first Java VM bin directory) will make that VM appear as
available.
On Windows systems, Java InstallShield currently searches the registry for available VM's. These are often missing or altered so that a valid VM might not appear in the available list. Make sure these following registry entries exist. If they do not, use regedit to add them and try running setup again.
My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\
JavaDevelopment Kit
My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\
JavaDevelopment Kit\1.2>
The first key should have one string value (other than 'Default') called "CurrentVersion" with a value of "1.2". The second key should have 2 string values. The first is named "JavaHome" with the value being the full path to your JDK installation directory. The second should be named "MicroVersion" and have a value of "0" if using the original JDK 1.2, or "1" if using 1.2.1, or "2" if using 1.2.2.
This solves 98% of problems Windows users have with Java InstallShield. If this does not solve your problem, please post to the developer list. Details for posting to this list are at the top of this document.
Answer:
iB-IDE's online help system is built around the JavaHelp
API. There are several JavaHelp documented bugs pertaining to
harmless exceptions being thrown when using the API. If the
help system is responding correctly despite the numerous
exceptions being thrown, you can safely ignore the exceptions.
You can always clear the exceptions from your display by
right clicking in the Message window and choosing to clear
messages.
Answer:
iB-IDE's online help system has several tutorials that
walk you through step-by-step writing your first iButton
project. The tutorials are located under Project Creation in
the online help and are called Host and Applet Tutorial and
Applet and APDUSender Tutorial.
Answer:
This error is caused by running previous versions of
iB-IDE under JDK 1.2.2. This JDK release introduced several
incompatibilities making it unusable with
iB-IDE. This problem has been accounted for in the current
release of iB-IDE. If you experience this problem, please
post to the developer list (see details at the
top of the page).
Answer:
Use com.dalsemi.system.Clock.getClock(). It is a static
method returning an int that contains the current value
of the clock in seconds.
Answer:
The Java Powered iButton conforms to the Java Card 2.0
specification. It communicates through APDUs and implements
the javacard.framework package. Programs written that adhere to the
Java Card standard will run on both the iButton and
a typical "smart-card-like" Java Card. However, you
will not be able to take the jib file (the converted applet)
and run it on another Java Card. Once the source has been compiled,
it must be converted to a hardware specific format (this is what
the BuildJiBlet tool does).
Also, be aware of differences between Java Card implementations.
The Java Powered iButton supports the Java Card cryptography
extensions, which are optional in the Java Card specification. There
are also a number of iButton specific classes (the
com.dalsemi packages) that will not be supported on other Java
Cards. In addition, the Java Powered iButton supports
integers (int), which is not included in the Java Card
specification.
Answer:
The 1.10 Release of iB-IDE now has support for modifying
classpaths. There are two CLASSPATH buttons on the
project window--one for
the applet and one for the host.
Answer:
Due to an oversight in the Java Powered iButton
Firmware Release 2.2.0007 only, the exception code byte for
a CoprocessorException is 0x00, which is also
the response from an iButton Get Last Error call that
means "No Error". If you perform a Get Last Error immediately
after recieving a 0x6F00 (Uncaught Exception), a response of
0x00 should mean "CoprocessorException".
Answer:
The 1.10 Release of iB-IDE now has support for
debugging applets that use the iButton's
cryptographic functions. In order to avoid legal
issues, you must download Sun's Java
Cryptography Extension (JCE) from
"http://www.javasoft.com/products/jce/index.html".
The JCE includes a JAR file that you must put in your
classpath, either by including it manually or by putting
the file in the same directory iB-IDE puts the files
jibapi.jar, exportable_ocf.jar, and others:
[JDK home]/jre/lib/ext.
Note that you can still use the emulators without
downloading the JCE, but you will not be able to access
the emulated cryptographic features.
This release of iB-IDE was developed using JCE 1.2.
Answer:
This can occur when the fonts used by iB-IDE
cannot be found. The program will use default fonts
instead, but the breakpoints are positioned based on
the size of the requested fonts. The breakpoints
are really there, they are just being drawn in the
wrong place.
Answer:
These files contain debug information about the applet,
matching code to line number and storing the class and
method numbers for the applet. They are mainly used
by the emulator for implementing breakpoints. If you are
building applets without using the iB-IDE, you do
not need to build these files. However, if you would like
to look at this debug information, use the '-b' and
'-j' switches of BuildJiBlet.
Answer:
iB-IDE does not run programs in a new process, but rather runs them
by calling their main method in a thread. This allows iB-IDE to
use the iButton Emulator. However, this makes cleaning up
hard, because listeners for iButton events might not go away.
What is happening in this case is that OpenCard has several listeners
that registered themselves with previous runs of your program, and could
not be cleaned up. To work around this problem, you can do either of the
following:
cleanUp() method into your host. To work,
this must be in the same class file that implements
opencard.core.event.CTListener. This method will be called from
iB-IDE after your program terminates. The following code is used
in the OpenCard host source templates. Do the same thing in your code
make sure iB-IDE can clean up properly.
public static void main(String[] args)
{
//The following path has been auto-generated by
//the Project Wizard. If the project is moved
//to a different directory, you MUST update this
//path accordingly.
ct_listener_object = new MyHost( . . . );
}
private static CTListener ct_listener_object = null;
public static void cleanUp()
{
if (ct_listener_object!=null)
{
CardTerminalRegistry reg = CardTerminalRegistry.getRegistry();
reg.removeCTListener(ct_listener_object);
}
}
iButton Homepage: http://www.ibutton.com/
