pcsc-relay: documented android smart card emulator

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;
 

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
 ********************

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
 

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