summaryrefslogtreecommitdiff
path: root/taler-nfc-guide.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2019-09-13 01:06:54 +0200
committerFlorian Dold <florian.dold@gmail.com>2019-09-13 01:07:34 +0200
commite064a0288e67601955890e85af0e2ee89704a21e (patch)
tree9ba672d939c18292e893e1aeb90a6d2c659438e9 /taler-nfc-guide.rst
parent2291f3c9120983f802f1a0dfc97c713df816cb03 (diff)
downloaddocs-e064a0288e67601955890e85af0e2ee89704a21e.tar.gz
docs-e064a0288e67601955890e85af0e2ee89704a21e.tar.bz2
docs-e064a0288e67601955890e85af0e2ee89704a21e.zip
first draft of NFC guide
Diffstat (limited to 'taler-nfc-guide.rst')
-rw-r--r--taler-nfc-guide.rst167
1 files changed, 167 insertions, 0 deletions
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
+
+
+