Merge branch 'master' of git.taler.net:docs

2 files changed, 61 insertions, 2 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 249f917a..246bc8cf 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -104,7 +104,7 @@ HTTP API
         // Identification token of the bank.  Not required to obey to any particular standard.
         recipient: string;
 
-        // Electronic signature version.  Admitted values: A004, A005, A006.
+        // Electronic signature version.  Admitted values: A005, A006.
         version: string;
 
         // Length in bits of the key exponent.
diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst
index 605bd971..58c22d24 100644
--- a/libeufin/ebics.rst
+++ b/libeufin/ebics.rst
@@ -342,6 +342,28 @@ The following order types are, for now, not relevant for LibEuFin:
     HAC order type.
 
 
+EBICS Message Format
+====================
+
+The following elements are the allowed root elements of EBICS request/response messages:
+
+* ``ebicsHEVRequest`` / ``ebicsHEVResponse``:  Always unauthenticated and unencrypted.  Used
+  **only** for query/response of the host's EBICS version.
+* ``ebicsUnsecuredRequest``: Request without signature or encryption (beyond TLS).  Used for INI and HIA.
+* ``ebicsKeyManagementResponse``:  Unauthenticated response.  Used for key management responses and
+  sometimes **also** to deliver error messages that are not signed by the bank (such as "invalid request").
+* ``ebicsNoPubKeyDigestsRequest``: Signed request that *does not* contain the hash of the bank's
+  public key that the client expects.  Used for key management, specifically only the HPB order type.
+* ``ebicsRequest`` / ``ebicsResponse``
+* ``ebicsUnsignedRequest``: Not used anymore.  Was used in FTAM migration with the HSA order type.
+
+
+Order ID Allocation
+===================
+
+In practice, the Order ID seems to be allocated via number of counters at the level of the **PartnerID**.
+
+
 EBICS Transaction
 =================
 
@@ -432,7 +454,7 @@ RSA key pairs are used for three purposes:
 
 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..
+The bank-technical key pair may not be used for any other purpose.
 
 
 Real-time Transactions
@@ -491,6 +513,43 @@ HypoVereinsbank
 
 See `this document <https://www.hypovereinsbank.de/content/dam/hypovereinsbank/shared/pdf/Auftragsarten_Internet_Nov2018_181118.pdf>`__.
 
+
+Cryptography
+============
+
+EBICS uses the XML Signature standard for signatures.  It does *not* use XML encryption.
+
+The EBICS specification doesn't directly reference the standardized URIs for the various
+signing algorithms.  Some of these URIs are defined in `<https://tools.ietf.org/html/rfc6931>`__.
+
+* A005 is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
+
+  * the ``RSASSA-PKCS1-v1_5`` signature scheme contains the ``EMSA-PKCS1-v1_5`` encoding scheme
+    mentioned in the EBICS spec.
+
+* A006 is `<http://www.w3.org/2007/05/xmldsig-more#rsa-pss>`__ as defined in RFC 6931.
+
+XML Signatures
+--------------
+
+XML Signatures can be a combination of:
+
+* detached (referencing another document)
+* enveloping (signs over ``Object`` tags *within* the ``Signature`` elements)
+* enveloped (signs over arbitrary data (via XPath expression) in other parts of the document
+  that contains the signature).
+
+In EBICS, only **enveloped** signatures are used.
+
+In the XML Signature standard, the element for a signature is ``Signature``.  EBICS violates this
+standard by always mandating ``AuthSignature`` as the name.  ``AuthSignature`` is an alias to
+the ``SignatureType`` xsd type in the XML Schema.
+
+Canonicalization vs transforms:
+ * Canonicalization refers to the processing of the ``SignedInfo`` element.
+ * Transformations apply to the data that ``Reference`` elements reference.  Canonicalization
+   algorithms can be used as a transformation on referenced data.
+
 Standards and Resources
 =======================