[dd 52] document current design solutions

2 files changed, 124 insertions, 0 deletions

diff --git a/design-documents/052-libeufin-bank-2fa.rst b/design-documents/052-libeufin-bank-2fa.rst
new file mode 100644
index 00000000..18ee82e2
--- /dev/null
+++ b/design-documents/052-libeufin-bank-2fa.rst
@@ -0,0 +1,123 @@
+DD 51: LibEufin Bank Two-factor authentification
+################################################
+
+Summary
+=======
+
+This document proposes designs for supporting 2-FA for more operations in 
+libeufin-bank.
+
+Motivation
+==========
+
+Currently, only cashout operations are protected using 2-FA and we want to also 
+protects withdrawal, transactions, account reconfiguration and account deletion.
+
+Requirements
+============
+
+* Support future TAN channels (YubiKey, trusted devices, etc) without API-breaking changes
+* Support mulitple TAN channels per user
+
+Proposed Solutions
+==================
+
+2 kinds of operations
+^^^^^^^^^^^^^^^^^^^^^
+
+We have two kinds of operations we would like to protect:
+
+* state-machine operations that already have a ``pending`` and ``confirmed`` status and require multiple endpoint calls to complete (cashout and withdrawal).
+* one-shot operations that are currently completed using a single endpoint call (transaction, account reconfiguration and account deletion).
+
+We could choose different designs for each kind of operation, as they have different implementation challenges.
+
+Fine-grained or coarse-grained authentification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fine-grained authorization is when one challenge is linked to a unique unalterable operation. They are the most secure and have the usability advantage that clients can show users exactly what they are allowing. They are complicated to implement especially for one-shot operations.
+* Coarse-grained authorization is when each challenge allows to perform one or many protected operations of any kind. They are the simplest to implement and might be enough for our needs.
+
+We should also take in consideration how hard it would be to maintain the solution and how hard it would be to protect a new kind of operation in the future.
+
+State machines operations only
+------------------------------
+
+If we transform all operations to become state-machine ones, we can use the same design currently used for cashout operations. All operations are created in a ``pending`` state and need to be confirmed later. The TAN challenge code is sent when the operation is created and checked during confirmation. Operation creation is idempotent and can be used to trigger code retransmission.
+
+The good
+^^^^^^^^
+
++ Fine-grained authorization
+
+The bad
+^^^^^^^
+
+- Requires to store pending operations in the database, requires new tables to store pending state for one-shot ones
+- Requires to add many endpoints to track operations status, list pending operations, confirm operations, etc
+- Requires to mix TAN challenge logic with operation logic, this means asking for TAN channel alongside operation data and returning TAN specific error in all operation creation and confirmation endpoints, therefore TAN logic changes can impact all those endpoints
+- Operation logic rewrite
+- Big backend and database change (new table or column and new API per operation)
+
+
+Centralized 2FA endpoints
+-------------------------
+
+To improve upon the previous design we can separate endpoints to perform TAN challenges from operation ones. When creating operations they return a challenge ID that can be used with TAN-specific endpoints to receive and solve a challenge. Those endpoints will handle the TAN channel choice and TAN-specific errors. Protected endpoints will error when a pending challenge hasn't been solved.
+
+The good
+^^^^^^^^
+
++ Fine-grained authorization
++ Centralized TAN challenge logic and error handling, TAN logic changes only impact TAN-specific endpoints
+
+The bad
+^^^^^^^
+
+- Requires to store pending operations in the database
+- Requires adding many endpoints to track operations status, confirm operations, list pending operations, etc.
+- Operation logic rewrite
+- Big backend and database change (new table or column and new API per operation)
+
+2FA tokens
+----------
+
+To improve upon the previous design, if coarse-grained authorization is enough, we can have a simpler design where a successful challenge produces a one-use 2FA token. Protected endpoints will error when a 2FA token is required and the token is provided through an HTTP header.
+
+We could require a 2FA token when confirming state-machine operations or when performing one-shot ones. Removing the need for new database tables and operation endpoints.
+
+The good
+^^^^^^^^
+
++ Existing database tables stay the same
++ Centralized TAN challenge logic and error handling
++ Most endpoints stay the same except the cashout API
++ Can protect new operations without changing their logic but need to add token consumption logic to the database transaction
++ Small backend and database change per operation (token consumption logic)
+
+The bad
+^^^^^^^
+
+- Using a nonstandard header can be complicated for some clients
+- The pending state of one-shot operations is kept at the client level, this is a simplification for the backend but we do not want to lose this state. This might be easy to do as all oneshot operations are simple ones and the token can be obtained in advance.
+- Coarse-grained authorization, one token for any operation. We could fix this by adding a ``kind`` field and an optional ``operation_id`` (state-machine operation) or ``operation_body`` (one-shot operations) field per challenge but this is ugly.
+
+2FA auth tokens
+---------------
+To improve upon the previous design, we could reuse the existing authentification token logic and create a new scope, ``2fa``, that works as an augmented ``readwrite``. Those auth tokens would be valid for a short amount of time (~3 minute) and would not be refreshable.
+
+The good
+^^^^^^^^
+
++ Existing database tables stay the same
++ Centralized TAN challenge logic and error handling
++ Most endpoints stay the same except the cashout API
++ Can protect new operations without changing their logic
++ Trivial backend and database change per operation (one line of code per operation)
+
+The bad
+^^^^^^^
+
+- Having a short-term token in addition to a long-term refreshable token can be confusing for clients.
+- We still keep the pending state of one-shot operations at the client level.
+- Coarse-grained authorization, one token for any operation for a short amount of time.
diff --git a/design-documents/index.rst b/design-documents/index.rst
index eba03307..b37d8860 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -63,4 +63,5 @@ Design documents that start with "XX" are considered deprecated.
   049-auth.rst
   050-libeufin-nexus.rst
   051-fractional-digits.rst
+  052-libeufin-bank-2fa.rst
   999-template