-
Notifications
You must be signed in to change notification settings - Fork 3
/
README
248 lines (200 loc) · 9.92 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
Title : JPCSC: JNI-wrapper for PCSC
Author : Marcus Oestreicher
Version : 0.7.7
License : IBM Alphaworks Source Code License, see License.html
Requires: JDK with JNI support (>= 1.3), PCSC Lite (> 1.0)
CONTENTS
========
0) PURPOSE
1) INSTALLATION
2) USAGE
3) STATUS
4) DESIGN
5) CONTACT
6) WINDOWS SUPPORT
7) CHANGES
8) MISCELLANEOUS PACKAGES
9) JCOP SIMULATION IFDHANDLER
1) PURPOSE
JPCSC provides a simple JNI library to allow for the access of PCSC
functions from Java. It offers an API to access most of the Card-
and Context-related functions, i.e. establish a context, list readers,
open a reader connection, and send APDUs to a reader and card.
JPCSC supports both Windows and Linux, a port to MacOSX should
be easy. JPCSC does not offer any advanced, application- or
card-specific APIs (such as OpenCard), it just provides a
resource-efficient and simple access to the smartcard infrastructure
available on most desktop systems as of today, i.e. PCSC.
0) INSTALLATION:
BINARY INSTALLATION
The JPCSC package now contains precompiled binaries for both Linux and Windows.
The Linux library libjpcsc.so has been compiled and tested on Fedora Core 1
and Debian Sid, your success with other glibc's and distributions may vary.
The Windows library has been built on Windows 2000 using Microsoft
Visual C++ Version 6.
You can test the precompiled libraries, before trying to rebuild
JPCSC. In case of Linux, edit Config in the top-level directory
to specify the location of your PCSC installation (/usr/local/pcsc
by default). Then, type "make testbin". The test program asks for a
reader to connect to, waits for a card, and then asks for the APDUs
to send to the card. Type 'quit' to end the Test program.
You can also try out "make toolbin" which starts a Swing
application allowing you to connect to PCSC readers and cards,
to select Applets on a card, and to send arbitrary APDUs
to the applet or card. The application especially traces all
the data sent to and received from the card.
COMPILATION
Edit Config in the top directory. If you want to compile JPCSC
on Windows, read the last section as well.
In case of Linux, specify the base directory of your PCSC
installation (typically /usr in case of an installation from
a debian or RPM package or /usr/local/pcsc). Use a recent
PCSC version, for instance 1.1.
PCSC_PACKAGE_NAME specifies the package name the JPCSC package
uses. "com.linuxnet.jpcsc" is the default, but modifying the
package name may allow for a better integration into your
application,
ENABLE_TRACING controls the output of debugging information,
use "yes" to get log output during JPCSC execution.
INSTALL_DIR finally specifies the directory where to install
the libraries and documentation. They will be stored in
${INSTALLDIR}/lib, ${INSTALLDIR}/share/java and
${INSTALLDIR}/share/doc/jpcsc.
Type "make". The libraries, test application and documentation
is built and stored in the build directory. Use "make test"
to test JPCSC before you install it. The test program asks for a
reader to connect to, waits for a card, and then asks for the APDUs
to send to the card. Type 'quit' to end the Test program.
Type "make bins" to build everything and copy the libraries to
the bin folder. Documentation can be found in apidocs.
Use "make all && make debpkg" to build a debian package. It can
be found in build/debian/jpcsc*deb after a successful build.
After "make all", you can use "make rpmpkgs" to build a
RPM package on a RPM based system. By default, it tries to
build the package in /usr/src/redhat, and thus, typically expects
root priviledges.
2) USAGE:
If you are familiar with Java, PCSC and native libraries,
using JPCSC should be easy. The JPCS jar-file must be listed
in your CLASSPATH, the directory where libjpcsc.so
is installed may have to be listed in your LD_LIBRARY_PATH
(or in ld.so.conf). Additionally, the dynamic linker
must be able to find libpcsc-lite.so.
Check back with the Makefile in the src/samples directory
to find out how to setup correctly all necessary paths.
When installing a RPM or Debian package, you can run
the test program as follows:
java -cp /usr/share/doc/jpcsc-0.7.6/samples.jar:/usr/share/java/jpcsc.jar samples.Test
3) STATUS:
Most of the functions found in PCSClite and in case of Windows
are accessible. The JNI wrapper is fairly simple and should be
easy to fix in case you encounter any problems.
4) DESIGN:
The package supports basically two classes, Context and
Card. If you are familiar with the PCSC lite API, you will
immediately feel comfortable. With Context, you establish
the communication with the PCSC daemon, query readers and
setup a connection with a card. This results in a Card
instance which is used to exchange APDUs with the card.
Error are typically signaled by PCSCExceptions. The State
class wraps structures such as READER_STATE and is used to
return the status of readers and card connections such
as in Context.GetStatusChange() or Card.Status().
The Context and Card class methods are mapped pretty much
straight to native functions. PCSC constants are
defined in PCSC.java. Their values depend on the underlying
platform, Linux or Windows, but are mapped accordingly at
JPCSC initialization time.
5) CONTACT
If you have questions or comments, feel free to contact me
at [email protected] or search for more information
at www.zurich.ibm.com/javacard
6) WINDOWS SUPPORT
The Makefile uses the Microsoft Visual Studio 6 C-compiler and
expects the cygnus-tools like cpp to be setup correctly. JPCSC
should then compile as cleanly as on Linux.
7) CHANGES:
0.7.6: bug-fixes and minor extensions, thanks to Martin Leung, [email protected], and others
- rpm and debian package build support
- Allowing external modification to Apdu (e.g. adding of secure messaging) by:
make Apdu.java serializable and add a wrapWith method
add interface Apdu.Wrapper
- Allow protocol T0|T1 in Context.connect()
- More details in State.toString():
State.toString() can now either log the flags according to a Card.Status() or
Context.GetStatusChange() invocation
- Add boolean field resendOnWrongLe to Card.java & jpcsc.c
automatically resend on 6cxx will fail if secure messaging is applied.
In this case, resend requires a different hash in the apdu.
- Use system error message on Win32 platform
On win32, many errors thrown by Resource Manager are not SCARD_*,e.g. 0x6,0x17,0x3e3,etc. Using
native error msg would make the err msg more readable.
- Add fix for the beginTransaction reset bug on Win9x/winxpsp1.
- New methods:
Context.WaitForCard(): blocks for a card to be inserted. Demonstrates proper use to
GetStatusChange() for blocking correctly on both Linux and Windows.
GetStatusChange() now returns boolean to signal whether it has been timed out or not.
0.7.5:
- Windows build is up-to-date again and does not fail due to an initializer error
- Documentation fixes thanks to Ville Skytta ([email protected])
- Added misc directory which contains a pcsc-ifdhandler for testing pcsc and jpcsc
applications with JCOP simulations
- Fixed CardControl:
- native funtion declaration was invalid
- windows expects the use of CARD_CTL_CODE to create a proper control code for CardControl()
0.7.4:
- Parameters passed are checked, especially PROTOCOL_T0 etc.
- GetStatusShange(timeout, NULL) supported.
- PCSC.INFINITE constant introduced.
- Context.Connect() introduced, connects to the first available card
in the system.
0.7.3:
- Bug-fix Release (Thanks to Wei-Ching Su, [email protected])
- Introduced the bin folder to contain the pre-built libraries.
0.7.2:
- Bug-fix Release (Thanks to Martin Leung, [email protected])
0.7.1:
- JPCSC now handles get-reponse in case of T=0 transparently by default.
- The class Card still offers a getT0GetResponse and setT0GetResponse
method to switch this behavior on and off in case.
0.7:
- JNI related bug fixes, a pretty nasty bug when used with JDK 1.4.2 fixed.
0.6:
- Apdu.java added to jpcsc. Allows to define APDU header and data to send and/or
receive from card. Especially, it allows to convert from bytearray
to string representation and vice versa.
- ListReaderGroups() now supported by jpcsc.
0.5:
- int Card.Transmit(byte[] in, int inOff, int inLen, byte[] out, int outOff)
now raises an exception in case of an error, otherwise, the number
of bytes received in out is returned
0.4:
- a simple apdu tool has been added, it allows selection of reader,
connection to card, and sending arbitrary APDUs
- include both jpcsc.dll and jpcsc.lib in build directory
- PCSC.java also contains now PCSC error and warning codes, additionally,
all codes are now kept in final static fields. Source and build tree
reorganized so that both Linux and Windows binaries can be shipped
with the source code. Makefile environment updated.
- Special thanks to Ross Burton ([email protected]) for the many contributions
to this release.
0.3:
- Context.c has been removed, applications are now expected to
instantiate Context-instances themselfes. Codes.java
has been moved to PCSC.java. Other than that, bug fixes.
0.2:
- jpcsc sets at initialization time the values for the parameters
and flags PCSC expects and returns (see PCSC.java and Context.c).
8) MISCELLANEOUS PACKAGES
You can find miscellaneous software packages in the misc subdirectory. The
only available package for now is a PCSC ifdhandler which simulates a simple
reader and connects to a running JCOP simulation process
(see www.zurich.ibm.com/javacard for more information).
9) JCOP SIMULATION IFDHANDLER
The JCOP PCSC ifdhandler simulates a simple reader and connects to a running
JCOP simulation process (see www.zurich.ibm.com/javacard for more information).
It allows to use all PCSC client software to talk to a JCOP simulation
process and executed JavaCard applets, and thus, allows to debug
both C-based PCSC client software and Javacard applets to be debugged at the
same time. Have a look into the misc/jcop_simul_ifdhandler subdirectory for
more information.