[GNUnet-SVN] [taler-docs] branch master updated (7c4b953 -> 0d448e7)

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a change to branch master
in repository docs.

    from 7c4b953  test commit
     new 2291f3c  manual naming
     new e064a02  first draft of NFC guide
     new 0d448e7  taler URI

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 core/taler-uri.rst        |   2 +
 index.rst                 |   1 +
 taler-exchange-manual.rst |   4 +-
 taler-merchant-manual.rst |   4 +-
 taler-nfc-guide.rst       | 167 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 174 insertions(+), 4 deletions(-)
 create mode 100644 taler-nfc-guide.rst

diff --git a/core/taler-uri.rst b/core/taler-uri.rst
index d69b4b0..c7b950d 100644
--- a/core/taler-uri.rst
+++ b/core/taler-uri.rst
@@ -1,3 +1,5 @@
+.. _taler-uri-scheme:
+
 ====================
 The taler URI scheme
 ====================
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-exchange-manual.rst b/taler-exchange-manual.rst
index 363a8f9..b10e2f8 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1,5 +1,5 @@
-The GNU Taler Exchange Operator Manual
-######################################
+GNU Taler Exchange Operator Manual
+##################################
 
 Introduction
 ============
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 16df4d5..d668de3 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1,5 +1,5 @@
-The GNU Taler manual for Web shops
-##################################
+GNU Taler Merchant Backend Operator Manual
+##############################################
 
 Introduction
 ============
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
+
+
+

-- 
To stop receiving notification emails like this one, please contact
address@hidden.