first draft of NFC guide

2 files changed, 168 insertions, 0 deletions

diff --git a/index.rst b/index.rst
index f85aa78..060795f 100644
--- a/index.rst
+++ b/index.rst
@@ -53,6 +53,7 @@ Documentation Overview
   core/index
   taler-exchange-manual
   taler-merchant-manual
+  taler-nfc-guide.rst
   taler-merchant-api-tutorial
   taler-bank-manual
   taler-backoffice-manual
diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst
new file mode 100644
index 0000000..e610b4c
--- /dev/null
+++ b/taler-nfc-guide.rst
@@ -0,0 +1,167 @@
+GNU Taler NFC Guide
+###################
+
+This guide explains how NFC (near-field communication) is used in the GNU Taler payment system.
+
+Introduction
+============
+
+NFC is currently used for two different purposes:
+
+1. Operations in the wallet (payment, withdrawal, ...) can be triggered by a
+   merchant PoS (Point-of-Sale) terminal or Taler-capable ATM.
+2. When either the wallet or the merchant do not have Internet connectivity,
+   the protocol messages to the exchange or merchant backend service can be tunneled via NFC
+   through the party that has Internet connectivity.
+
+
+Background: Payment Processing with GNU Taler
+=============================================
+
+The following steps show a simple payment process with GNU Taler.  Examples are
+written in `Bash <https://www.gnu.org/software/bash/>`_ syntax,
+using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) requests.
+
+1. The merchant creates an *order*, which contains the details of the payment and the product/service
+   that the customer will receive.
+   An order is identified by an alphanumeric *order ID*.
+   
+   The following :http:post:`/order` request creates a simple order:
+
+   .. code-block:: sh
+ 
+    $ backend_base_url=https://backend.demo.taler.net/
+    $ auth_header='Authorization: ApiKey sandbox'
+    $ order_req=$(cat <<EOF
+      {
+        "order": {
+          "summary": "one ice cream",
+          "amount": "KUDOS:1.5",
+          "fulfillment_url":
+            "taler://fulfillment-success/Enjoy+your+ice+cream!"
+       }
+      }
+    EOF
+    )
+    $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/order
+    {
+      "order_id": "2019.255-02YDHMXCBQP6J"
+    }
+
+2. The merchant checks the payment status of the order using :http:get:`/check-payment`:
+
+   .. code-block:: sh
+ 
+     $ backend_base_url=https://backend.demo.taler.net/
+     $ auth_header='Authorization: ApiKey sandbox'
+     $ curl -XGET -H"$auth_header" \
+        "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J"
+     # Response:
+     {
+       "taler_pay_uri": "taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J",
+       "paid": false,
+       # ... (some fields omitted)
+     }
+
+   As expected, the order is not paid.  To actually proceed with the payment, the value of ``taler_pay_uri``
+   must be processed by the customer's wallet.  There are multiple ways for the wallet to obtain the ``taler://pay/`` URI
+
+   * in a QR code
+   * in the ``Taler:`` HTTP header of a Web site
+   * by manually entering it in the command-line wallet
+   * **via NFC** (explained in this guide)
+
+   The details of ``taler://`` URIs are specified :ref:`here <taler-uri-scheme>`.
+
+3. The wallet processes the ``taler://pay/`` URI.  In this example, we use the command line wallet:
+
+   .. code-block:: sh
+
+     # Withdraw some toy money (KUDOS) from the demo bank
+     $ taler-wallet-cli test-withdraw \
+       -e https://exchange.demo.taler.net/ \
+       -b https://bank.demo.taler.net/ \
+       -a KUDOS:10
+     # Pay for the order from the merchant.
+     $ taler-wallet-cli pay-uri 'taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J'
+     # [... User is asked to confirm the payment ...]
+
+4. The merchant checks the payment status again:
+
+   .. code-block:: sh
+ 
+     $ backend_base_url=https://backend.demo.taler.net/
+     $ auth_header='Authorization: ApiKey sandbox'
+     $ curl -XGET -H"$auth_header" \
+        "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J"
+     # Response:
+     {
+       "paid": true,
+       # ... (some fields omitted)
+     }
+
+
+Taler NFC Basics
+================
+
+The NFC communication in GNU Taler follows the ISO-DEP (`ISO 14443-4
+<https://www.iso.org/standard/73599.html>`_) standard.  The wallet always acts
+as a tag (or more precisely, emulated card), while the merchant PoS terminal
+and bank terminal act as a reader.
+
+The basic communication unit is the application protocol data unit (`APDU
+<https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit>`_), with the structure
+and commands defined in `ISO 7816 <https://cardwerk.com/iso-7816-smart-card-standard>`_.
+
+The GNU Taler wallet uses the AID (application identifier) ``F00054414c4552``.
+The ``F`` prefix indicates the proprietary/unregistered namespace of AIDs, and
+the rest of the identifier is the hex-encoded ASCII-string ``TALER`` (with one 0-byte left padding).
+
+During the time that wallet is paired with a reader, the communication channel is stateful.
+Most importantly, the first message sent by the reader to the wallet must be a ``SELECT FILE (=0xA4)`` that selects
+the GNU Taler AID.
+
+The reader sends commands to the wallet with the ``PUT DATA (=0xDA)`` instruction, using the instruction parameters ``0x0100``,
+denoting a proprietary instruction.
+
+The command data of the ``PUT DATA`` APDU is prefixed by a one-byte Taler instruction ID (TID).  Currently, the following TIDs
+are used:
+
+.. list-table::
+  :widths: 5 50
+  :header-rows: 1
+
+  * - TID
+    - Description
+  * - ``0x01``
+    - Dereference ``taler://`` URI (UTF-8 encoded) in the remainder of the command data.
+  * - ``0x02``
+    - Accept the UTF-8 encoded JSON object in the remainder of the command data as a request tunneling response.
+
+
+
+Sending taler URIs to the Wallet via NFC
+========================================
+
+To make the wallet process an order via NFC, the merchant PoS terminal sends ``SELECT FILE`` command with the Taler AID,
+and a ``PUT DATA`` command with the Taler instruction ID ``0x01`` and the URI in the rest of the command data.
+
+Here is an example protocol trace from an interaction which caused the wallet to dereference
+the ``taler://pay`` URI from the example above:
+
+.. code:: none
+
+  # SELECT FILE
+  m->w 00A4040007F00054414c4552
+  # success response with no data
+  m<-w 9000
+
+  # PUT DATA (TID=1)
+  m->w 00DA01007c0174616c65723a2f2f7061792f6261636b656e642e64656d6f2e74
+       616c65722e6e65742f2d2f2d2f323031392e3235352d30325944484d58434251
+       50364a
+  # success response with no data
+  m<-w 9000
+
+
+