ds.ov2.util
Class Card_terminal

java.lang.Object
  ds.ov2.util.Card_terminal

public class Card_terminal
extends Object

Various utility methods for makeing connections to cards (or emulators) and applet selection. This is a static class.

CPP Preprocessing

no cpp preprocessing needed

Execution Environment:

host

To Do:

add sun_provider_present

Author:

Hendrik Tews

Version:

$Revision: 1.24 $

Last Commit:

$Date: 2009-06-17 20:14:05 $ by $Author: tews $

Nested Class Summary

static class	Card_terminal.Applet_selection_exception Exception indicating that applet selection failed.
static class	Card_terminal.Terminal_type Enumeration type for card terminals and emulators.

Constructor Summary

protected

Card_terminal() Object creation is disabled, because all fields are static.

Method Summary

static void	add_jcop_provider() Loads the Provider for the JcopEmulator TerminalFactory that gives access to a jcop emulator via the javax.smartcardio package.
static void	close_connection(PrintWriter out, CardChannel card_channel) Close a card channel and disconnect the connection to the card.
static List<CardTerminal>	get_all_jcop_emulators(Object o) Returns a terminal list for connecting to the jcop emulator.
static List<CardTerminal>	get_all_pcsc_terminals() Return a list of all PC/SC terminals connected to this machine.
static List<CardTerminal>	get_all_sun_emulators(Object o) Returns a terminal list for connecting to one of the SUN emulators (cref or jcwde).
static boolean	jcop_provider_present() Tests the presence of the libraries for connecting to a jcop emulator.
static void	open_applet_ex(CardChannel channel, byte[] applet_id, PrintWriter out, boolean apduscript) Applet selection.
static void	open_applet(CardChannel channel, byte[] applet_id, PrintWriter out, boolean apduscript) Wrapper for open_applet_ex.
static CardChannel	open_card_channel_ex(int terminal_number, Card_terminal.Terminal_type terminal_type, Object o, PrintWriter out) Connect to a card (or emulator) and return the basic channel.
static CardChannel	open_card_channel(int terminal_number, Card_terminal.Terminal_type terminal_type, Object o, PrintWriter out) Wrapper for open_card_channel_ex.
static void	print_readers(PrintWriter out) Print a list of all connected PC/SC card terminals.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Card_terminal

protected Card_terminal()

Object creation is disabled, because all fields are static.

Method Detail

get_all_pcsc_terminals

public static List<CardTerminal> get_all_pcsc_terminals()
                                                 throws NoSuchAlgorithmException,
                                                        CardException

Return a list of all PC/SC terminals connected to this machine.

Returns:

the list of terminals

Throws:

CardException - for communication errors

NoSuchAlgorithmException - if the provider for the PC/SC terminal factory is absent (which should rarely occur, because this provider is in the JDK)

get_all_sun_emulators

public static List<CardTerminal> get_all_sun_emulators(Object o)
                                                throws NoSuchAlgorithmException,
                                                       CardException

Returns a terminal list for connecting to one of the SUN emulators (cref or jcwde). Loads the Provider for the SunEmulator TerminalFactory that gives access to one of the SUN emulators via the javax.smartcardio package. This works only if emulatorio.jar and apduio.jar are accessible at runtime.

Parameters:

o - argument for TerminalFactory.getInstance

Returns:

terminal list for connecting to a SUN emulator

Throws:

CardException - if one of the necessary libraries is missing or if communication error with the emulator occurs

NoSuchAlgorithmException - is never thrown when the right emulatorio.jar is provided.

add_jcop_provider

public static void add_jcop_provider()
                              throws CardException

Loads the Provider for the JcopEmulator TerminalFactory that gives access to a jcop emulator via the javax.smartcardio package. This will only succeed if both jcopio.jar and offcard.jar are in the class path.

Throws:

CardException - if adding the provider fails because one of the required jar files is missing.

jcop_provider_present

public static boolean jcop_provider_present()

Tests the presence of the libraries for connecting to a jcop emulator. Tries to load the Provider for the JcopEmulator TerminalFactory that gives access to a jcop emulator via the javax.smartcardio package. This will only succeed if both jcopio.jar and offcard.jar are in the class path. Returns true precisely if the provider is present and access to a jcop emulator is possible.

Returns:

true if a jcop emulator can be accessed, false if some of the necessary libraries are missing

get_all_jcop_emulators

public static List<CardTerminal> get_all_jcop_emulators(Object o)
                                                 throws NoSuchAlgorithmException,
                                                        CardException

Returns a terminal list for connecting to the jcop emulator. For that the appropriate provider is loaded via add_jcop_provider().

Parameters:

o - argument for TerminalFactory.getInstance

Returns:

a terminal list for accessing a jcop emulator

Throws:

CardException - if one of the necessary libraries is missing (see throws clause at add_jcop_provider()) or a communication problem is detected

NoSuchAlgorithmException - never thrown if the right libraries are used

print_readers

public static void print_readers(PrintWriter out)

Print a list of all connected PC/SC card terminals.

Parameters:

out - the channel to print to

open_applet_ex

public static void open_applet_ex(CardChannel channel,
                                  byte[] applet_id,
                                  PrintWriter out,
                                  boolean apduscript)
                           throws Card_terminal.Applet_selection_exception,
                                  CardException

Applet selection. Select the specified applet on the card cannel. Print the select APDU and other diagnostics to out if out is non null.

Parameters:

channel - the card channel to issue the select command

applet_id - the applet identifier

out - if non-null, channel for diagnostics

apduscript - if true print apduscript lines to out

Throws:

AppletSelectionException - if applet selection fails

CardException - for communication errors

Card_terminal.Applet_selection_exception

open_applet

public static void open_applet(CardChannel channel,
                               byte[] applet_id,
                               PrintWriter out,
                               boolean apduscript)

Wrapper for open_applet_ex. Calls open_applet_ex and prints any errors to out or System.err. If an error occurs the program is terminated.

Parameters:

channel - the card channel to issue the select command

applet_id - the applet identifier

out - if non-null, channel for diagnostics

apduscript - if true print apduscript lines to out

open_card_channel_ex

public static CardChannel open_card_channel_ex(int terminal_number,
                                               Card_terminal.Terminal_type terminal_type,
                                               Object o,
                                               PrintWriter out)
                                        throws CardException,
                                               NoSuchAlgorithmException

Connect to a card (or emulator) and return the basic channel. In the list of all available terminals of type terminal_type the one with index terminal_number is selected, a connection to the card there is made and the basic channel returned.

Parameters:

terminal_number - terminal index

terminal_type - determines whether to connect to a real terminal or to some emulator

o - argument for TerminalFactory.getInstance

out - if non-null print diagnostics and progress messages there

Returns:

the basic channel to the selected card or emulator

Throws:

CardException - if a library for connecting to one of the emulators is missing or another communication problem occurs (see also add_jcop_provider() and get_all_sun_emulators(java.lang.Object) which are used internally)

NoSuchAlgorithmException - is never thrown if the proper libraries are used.

open_card_channel

public static CardChannel open_card_channel(int terminal_number,
                                            Card_terminal.Terminal_type terminal_type,
                                            Object o,
                                            PrintWriter out)

Wrapper for open_card_channel_ex. Calls open_card_channel_ex and prints any error to out or System.err. The program is terminated if an error occurs.

Parameters:

terminal_number - terminal index

terminal_type - determines whether to connect to a real terminal or to some emulator

o - argument for TerminalFactory.getInstance

out - if non-null print diagnostics and progress messages there, if null, errors are printed to System.err

Returns:

the basic channel to the selected card or emulator

close_connection

public static void close_connection(PrintWriter out,
                                    CardChannel card_channel)

Close a card channel and disconnect the connection to the card.

Parameters:

out - channel to write error diagnostics, if the operation fails. If null System.err is used.

card_channel - the channel to close