ebics

2 files changed, 65 insertions, 32 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 25da91a1..35483f39 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -81,9 +81,6 @@ Receiving Payments
       // it has been paid for.  The wallet will always automatically append
       // the order_id as a query parameter.
       fulfillment_url: string;
-
-      // Merchant instance to use (leave empty to use instance "default")
-      instance?: string;
     }
 
   .. _PostOrderResponse:
@@ -104,7 +101,6 @@ Receiving Payments
   **Request:**
 
   :query order_id: order id that should be used for the payment
-  :query instance: *Optional*. Instance used for the payment. Defaults to the instance with identifier "default".
   :query session_id: *Optional*. Session ID that the payment must be bound to.  If not specified, the payment is not session-bound.
 
   **Response:**
@@ -179,9 +175,6 @@ Giving Refunds
 
       // Human-readable refund justification
       reason: string;
-
-      // Merchant instance issuing the request
-      instance?: string;
     }
 
   .. _MerchantRefundResponse:
@@ -263,9 +256,6 @@ Giving Customer Tips
       // Amount that the customer should be tipped
       amount: Amount;
 
-      // Merchant instance issuing the request
-      instance?: string;
-
       // Justification for giving the tip
       justification: string;
 
@@ -291,20 +281,14 @@ Giving Customer Tips
 
 .. http:post:: /tip-query
 
-  Query the status of an instance's tipping reserve.
-
-  **Request**
-
-  :query instance: instance to query
+  Query the status of a tipping reserve.
 
   **Response**
 
   :status 200 OK:
     A tip has been created. The backend responds with a `TipQueryResponse`_
-  :status 404 Not Found:
-    The instance is unknown to the backend.
   :status 412 Precondition Failed:
-    The instance does not have a tipping reserve configured.
+    The merchant backend instance does not have a tipping reserve configured.
 
   .. _TipQueryResponse:
   .. code-block:: tsref
@@ -340,7 +324,6 @@ Tracking Wire Transfers
   :query wtid: raw wire transfer identifier identifying the wire transfer (a base32-encoded value)
   :query wire_method: name of the wire transfer method used for the wire transfer
   :query exchange: base URL of the exchange that made the wire transfer
-  :query instance: (optional) identificative token of the merchant `instance <https://docs.taler.net/operate-merchant.html#instances-lab>`_ which is being tracked.
 
   **Response:**
 
@@ -457,7 +440,6 @@ Tracking Wire Transfers
   **Request:**
 
   :query id: ID of the transaction we want to trace (an integer)
-  :query instance:  merchant instance
 
   **Response:**
 
@@ -557,7 +539,6 @@ Transaction history
   :query date: time threshold, see `delta` for its interpretation.
   :query start: row number threshold, see `delta` for its interpretation.  Defaults to `UINT64_MAX`, namely the biggest row id possible in the database.
   :query delta: takes value of the form `N (-N)`, so that at most `N` values strictly younger (older) than `start` and `date` are returned.  Defaults to `-20`.
-  :query instance: on behalf of which merchant instance the query should be accomplished.
   :query ordering: takes value `descending` or `ascending` according to the results wanted from younger to older or vice versa.  Defaults to `descending`.
 
   **Response**
@@ -924,12 +905,6 @@ The `contract terms` must have the following structure:
       // label for a location that denotes the jurisdiction for disputes.
       // Some of the typical fields for a location (such as a street address) may be absent.
       jurisdiction: string;
-
-      // Which instance is working this proposal.
-      // See `Merchant Instances <https://docs.taler.net/operate-merchant.html#instances-lab>`_.
-      // This field is optional, as the "default" instance is not forced to provide any
-      // `instance` identificator.
-      instance: string;
     }
 
 
@@ -1120,7 +1095,6 @@ both by the user's browser and their wallet.
 
   **Request**
 
-  :query instance: the merchant instance issuing the request
   :query order_id: the order id whose refund situation is being queried
   :query nonce: the nonce for the proposal
 
diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst
index e818ac69..a47b109f 100644
--- a/libeufin/ebics.rst
+++ b/libeufin/ebics.rst
@@ -13,6 +13,15 @@ EBICS Glossary
 
 .. glossary::
 
+  A004
+    Electronic signature process, used in H004, deprecated in H005 with EBICS 3.0.
+
+  A005
+    Electronic signature process.  Used in H004 and H005.
+
+  A006
+    Electronic signature process.  Used in H004 and H005.
+
   BTF
     *Business Transaction Formats.*  Before EBICS 3.0, many different order types were
     used for business-related messages.  With EBICS 3.0, the more generic BTU and BTD
@@ -37,6 +46,10 @@ EBICS Glossary
       Transport signature.  Only used to verify authorized submission,
       but not to verify the bank-technical authorization.
 
+    In H004 and H005, the ES of the bank is specified as a "planned feature" that
+    is not actually implemented yet.  Thus banks in practice only use their
+    encryption key pair and authentication/identity key pair.
+
   EDS
     Distributed Electronic Signature.  Allows multiple subscribers to authorize an existing order.
    
@@ -47,6 +60,9 @@ EBICS Glossary
 
    See :term:`Subscriber`. 
 
+  H004
+    Host protocol version 4.  Refers to the XML Schema defined in *EBICS 2.5*.
+
   H005
     Host protocol version 5.  Refers to the XML Schema defined in *EBICS 3.0*.
 
@@ -79,13 +95,18 @@ EBICS Glossary
     and ``UserId``.  A technical subscriber cannot sign a bank-technical request.
 
   Technical Subscriber
-
    See :term:`Subscriber`. 
 
   TLS
     *Transport Layer Security*.  All messages in EBICS are sent over HTTP with TLS.
     In the current version of the standard, only server certificates are required.
 
+  VEU
+    Distributed Electronic Signature (from German "Verteilte Elektronische Unterschrift").
+
+  X002
+    Identification and authentication signature in H004 and H005.
+
 Order Types
 ===========
 
@@ -109,17 +130,55 @@ FUL
 FDL
   **Before EBICS 3.0, France**.  File Download.  Mainly used by France-style EBICS.
 
-HPD
+HIA
+  Transmission of the subscriber keys for (1) identification and authentication and (2)
+  encryption within the framework of subscriber initialisation.
+
+HPB
+  Query the three RSA keys of the financial institute.
+
+HP
   Host Parameter Data.  Used to query the capabilities of the financial institution.
 
-HVE:
+INI
+  Transmission of the subscriber keys for bank-technical electronic signatures.
+
+The following order types are, for now, not relevant for LibEuFin:
+
+H3K
+  Send all three RSA key pairs for initialization at once, accompanied
+  by a CA certificate for the keys.  This is (as far as we know) used in France,
+  but not used by any German banks.  When initializing a subscriber with H3K,
+  no INI and HIA letters are required.
+
+HVE
   Host Verification of Electronic Signature.  Used to submit an electronic signature separately
   from a previously uploaded order.
 
-HVS:
+HVD
+  Retrieve VEU state.
+
+HVD
+  Retrieve VEU overview.
+
+HVS
   Cancel Previous Order (from German "Storno").  Used to submit an electronic signature separately
   from a previously uploaded order.
 
+
+Key Management
+==============
+
+RSA key pairs are used for three purposes:
+
+1. Authorization of requests by signing the order data.  Called the *bank-technical key pair*.
+2. Identification/authentication of the subscriber.  Called the *identification and authentication key pair*.
+3. Decryption of the symmetric key used to decrypt the bank's response.  Called the *encryption key pair*.
+
+One subscriber *may* use three different key pairs for these purposes.
+The identification and authentication key pair may be the same as the encryption key pair.
+The bank-technical key pair may not be used for any other purpose..
+
 MT940 vs MT942
 ==============