From d4eb0830e529bbe0237eda7495b6425ed2fd6bf7 Mon Sep 17 00:00:00 2001 From: Frank Morgner Date: Tue, 24 Mar 2015 01:19:01 +0100 Subject: [PATCH] pcsc-relay: documented android smart card emulator --- .../acardemulator/SimulatorService.java | 16 ++--- ACardEmulator/doc/README.txt | 2 + pcsc-relay/doc/README.txt | 60 ++++++++++++++++++- pcsc-relay/doc/README.txt.in | 58 +++++++++++++++++- 4 files changed, 124 insertions(+), 12 deletions(-) diff --git a/ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java b/ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java index 3fb1fb0..e70954a 100644 --- a/ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java +++ b/ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java @@ -46,19 +46,21 @@ import pkgYkneoOath.YkneoOath; public class SimulatorService extends HostApduService { + private static final boolean useVPCD = false; + public static final int DEFAULT_PORT = 35963; + private static final String hostname = "192.168.42.158"; + private int port = DEFAULT_PORT; + + private static Socket socket; + private static InputStream inputStream; + private static OutputStream outputStream; + public static final String TAG = "com.vsmartcard.acardemulator.SimulatorService"; public static final String EXTRA_CAPDU = "MSG_CAPDU"; public static final String EXTRA_RAPDU = "MSG_RAPDU"; public static final String EXTRA_ERROR = "MSG_ERROR"; public static final String EXTRA_DESELECT = "MSG_DESELECT"; public static final String EXTRA_INSTALL = "MSG_INSTALL"; - public static final int DEFAULT_PORT = 35963; - private int port = DEFAULT_PORT; - private static final String hostname = "192.168.42.158"; - private static Socket socket; - private static InputStream inputStream; - private static OutputStream outputStream; - private static final boolean useVPCD = false; private static CardSimulator simulator = null; diff --git a/ACardEmulator/doc/README.txt b/ACardEmulator/doc/README.txt index 56a1347..d400583 100644 --- a/ACardEmulator/doc/README.txt +++ b/ACardEmulator/doc/README.txt @@ -51,6 +51,8 @@ The Android Smart Card Emulator has the following dependencies: For emulating a contact-less smart card with a desktop or notebook, have a look at :ref:`pcsc-relay`. +.. _acardemulator_install: + ******************** Download and Install ******************** diff --git a/pcsc-relay/doc/README.txt b/pcsc-relay/doc/README.txt index 7cfea04..166816f 100644 --- a/pcsc-relay/doc/README.txt +++ b/pcsc-relay/doc/README.txt @@ -21,7 +21,7 @@ PC/SC Relay Welcome to PC/SC Relay. The purpose of PC/SC Relay is to relay a smart card using an contact-less interface. Currently the following contact-less -backends are supported: +emulators are supported: - `Hardware supported by libnfc`_ - OpenPICC_ @@ -58,10 +58,10 @@ relayed to one of the following: (contactbased) {Contact-based Smart Card}; \node [kleiner, left=2cm of pcsc-relay, yshift=.3cm] (contactless) {Contact-less Smart Card}; - \node [kleiner, left=2cm of pcsc-relay, yshift=-.3cm] - (virtual) {Virtual Smart Card}; \node [kleiner, left=2cm of pcsc-relay, yshift=-.9cm] (remotereader) {Remote Smart Card Reader}; + \node [kleiner, left=2cm of pcsc-relay, yshift=-.3cm] + (virtual) {Virtual Smart Card}; \node [above=.3cm of pcsc-relay, kleiner, xshift=1.2cm] (capdu) {Command APDU}; @@ -210,6 +210,36 @@ configure PC/SC Relay to use it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig +==================================== +Hints on Android Smart Card Emulator +==================================== + +The Android Smart Card Emulator is build around the host card emulation mode of +Android 4.4 and later. This mode activates the app if the terminal issues a +SELECT command with one of the app's application identifiers. The app registers +for the following AIDs (:file:`ACardEmulator/app/src/main/res/xml/aid_list.xml`): + +.. literalinclude:: ../../ACardEmulator/app/src/main/res/xml/aid_list.xml + :language: xml + :emphasize-lines: 8,12,16,20 + +If used together with PC/SC Relay you need to change these application +identifiers to match the emulated card. Otherwise the app will not be activated +when it should relay command APDUs to PC/SC Relay. + +And while you are already modifying the Android Smart Card Emulator you may also +want to activate `useVPCD` and change `hostname` and `port` to configure the +connection to PC/SC Relay +(:file:`ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java`): + +.. literalinclude:: ../../ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java + :language: java + :lines: 47-52 + :emphasize-lines: 3,5-6 + +Compiling and installing Android Smart Card Emulator is covered in its :ref:`acardemulator_install` section. + + ========================= Hints on PC/SC middleware ========================= @@ -231,6 +261,30 @@ Usage .. program-output:: pcsc-relay --help +Below we explain what option to choose for the emulator which receives a +command APDU and transmits a response APDU back to the terminal: + +=================================================== ============== +Option ``--emulator`` +=================================================== ============== +Emulation hardware supported via libnfc ``libnfc`` +Emulation with OpenPICC ``openpicc`` +Android Smart Card Emulator ``vpcd`` +Virtual Smart Card ``vpcd`` +=================================================== ============== + +Below we explain what option to choose for the connector which calculates +a response APDU from a given command APDU: + +=================================================== =============== +Option ``--connector`` +=================================================== =============== +Contact-based Smart Card in PC/SC Reader ``pcsc`` +Contact-less Smart Card in PC/SC Reader ``pcsc`` +Contact-less Smart Card in Remote Smart Card Reader ``vicc`` +Virtual Smart Card ``vicc`` +=================================================== =============== + .. include:: questions.txt diff --git a/pcsc-relay/doc/README.txt.in b/pcsc-relay/doc/README.txt.in index fe2ffe2..33e8f86 100644 --- a/pcsc-relay/doc/README.txt.in +++ b/pcsc-relay/doc/README.txt.in @@ -58,10 +58,10 @@ relayed to one of the following: (contactbased) {Contact-based Smart Card}; \node [kleiner, left=2cm of pcsc-relay, yshift=.3cm] (contactless) {Contact-less Smart Card}; - \node [kleiner, left=2cm of pcsc-relay, yshift=-.3cm] - (virtual) {Virtual Smart Card}; \node [kleiner, left=2cm of pcsc-relay, yshift=-.9cm] (remotereader) {Remote Smart Card Reader}; + \node [kleiner, left=2cm of pcsc-relay, yshift=-.3cm] + (virtual) {Virtual Smart Card}; \node [above=.3cm of pcsc-relay, kleiner, xshift=1.2cm] (capdu) {Command APDU}; @@ -210,6 +210,36 @@ configure @PACKAGE_NAME@ to use it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig +==================================== +Hints on Android Smart Card Emulator +==================================== + +The Android Smart Card Emulator is build around the host card emulation mode of +Android 4.4 and later. This mode activates the app if the terminal issues a +SELECT command with one of the app's application identifiers. The app registers +for the following AIDs (:file:`ACardEmulator/app/src/main/res/xml/aid_list.xml`): + +.. literalinclude:: ../../ACardEmulator/app/src/main/res/xml/aid_list.xml + :language: xml + :emphasize-lines: 8,12,16,20 + +If used together with @PACKAGE_NAME@ you need to change these application +identifiers to match the emulated card. Otherwise the app will not be activated +when it should relay command APDUs to @PACKAGE_NAME@. + +And while you are already modifying the Android Smart Card Emulator you may also +want to activate `useVPCD` and change `hostname` and `port` to configure the +connection to @PACKAGE_NAME@ +(:file:`ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java`): + +.. literalinclude:: ../../ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java + :language: java + :lines: 47-52 + :emphasize-lines: 3,5-6 + +Compiling and installing Android Smart Card Emulator is covered in its :ref:`acardemulator_install` section. + + ========================= Hints on PC/SC middleware ========================= @@ -231,6 +261,30 @@ Usage .. program-output:: pcsc-relay --help +Below we explain what option to choose for the emulator which receives a +command APDU and transmits a response APDU back to the terminal: + +=================================================== ============== +Option ``--emulator`` +=================================================== ============== +Emulation hardware supported via libnfc ``libnfc`` +Emulation with OpenPICC ``openpicc`` +Android Smart Card Emulator ``vpcd`` +Virtual Smart Card ``vpcd`` +=================================================== ============== + +Below we explain what option to choose for the connector which calculates +a response APDU from a given command APDU: + +=================================================== =============== +Option ``--connector`` +=================================================== =============== +Contact-based Smart Card in PC/SC Reader ``pcsc`` +Contact-less Smart Card in PC/SC Reader ``pcsc`` +Contact-less Smart Card in Remote Smart Card Reader ``vicc`` +Virtual Smart Card ``vicc`` +=================================================== =============== + .. include:: questions.txt