052-libeufin-bank-2fa.rst (6799B)
1 DD 52: LibEufin Bank Two-factor authentification 2 ################################################ 3 4 Summary 5 ======= 6 7 This document proposes designs for supporting 2-FA for more operations in 8 libeufin-bank. 9 10 Motivation 11 ========== 12 13 Currently, only cashout operations are protected using 2-FA and we want to also 14 protects withdrawal, transactions, account reconfiguration and account deletion. 15 16 Requirements 17 ============ 18 19 * Support future TAN channels (YubiKey, trusted devices, etc) without API-breaking changes 20 * Support multiple TAN channels per user 21 22 Proposed Solutions 23 ================== 24 25 2 kinds of operations 26 ^^^^^^^^^^^^^^^^^^^^^ 27 28 We have two kinds of operations we would like to protect: 29 30 * state-machine operations that already have a ``pending`` and ``confirmed`` status and require multiple endpoint calls to complete (cashout and withdrawal). 31 * one-shot operations that are currently completed using a single endpoint call (transaction, account reconfiguration and account deletion). 32 33 Fine-grained or coarse-grained authentification 34 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 35 36 * 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. 37 * 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. 38 39 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. 40 41 State machines operations only 42 ------------------------------ 43 44 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. 45 46 The good 47 ^^^^^^^^ 48 49 + Fine-grained authorization 50 51 The bad 52 ^^^^^^^ 53 54 - Requires to store pending operations in the database, requires new tables to store pending state for one-shot ones 55 - Requires to add many endpoints to track operations status, list pending operations, confirm operations, etc 56 - 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 57 - Operation logic rewrite 58 - Big backend and database change (new table or column and new API per operation) 59 60 61 Centralized 2FA endpoints 62 ------------------------- 63 64 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. 65 66 The good 67 ^^^^^^^^ 68 69 + Fine-grained authorization 70 + Centralized TAN challenge logic and error handling, TAN logic changes only impact TAN-specific endpoints 71 72 The bad 73 ^^^^^^^ 74 75 - Requires to store pending operations in the database 76 - Requires adding many endpoints to track operations status, confirm operations, list pending operations, etc. 77 - Operation logic rewrite 78 - Big backend and database change (new table or column and new API per operation) 79 80 2FA tokens 81 ---------- 82 83 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. 84 85 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. 86 87 The good 88 ^^^^^^^^ 89 90 + Existing database tables stay the same 91 + Centralized TAN challenge logic and error handling 92 + Most endpoints stay the same except the cashout API 93 + Can protect new operations without changing their logic but need to add token consumption logic to the database transaction 94 + Small backend and database change per operation (token consumption logic) 95 96 The bad 97 ^^^^^^^ 98 99 - Using a nonstandard header can be complicated for some clients 100 - 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. 101 - 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. 102 103 2FA auth tokens 104 --------------- 105 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. 106 107 The good 108 ^^^^^^^^ 109 110 + Existing database tables stay the same 111 + Centralized TAN challenge logic and error handling 112 + Most endpoints stay the same except the cashout API 113 + Can protect new operations without changing their logic 114 + Trivial backend and database change per operation (one line of code per operation) 115 116 The bad 117 ^^^^^^^ 118 119 - Having a short-term token in addition to a long-term refreshable token can be confusing for clients. 120 - We still keep the pending state of one-shot operations at the client level. 121 - Coarse-grained authorization, one token for any operation for a short amount of time. 122 123 Q / A 124 ===== 125 126 * Q: Where do we want to handle TAN challenges logic and error handling, in each operation API or a TAN-specific API? 127 128 * In each operation means fewer API calls and TAN-specific means more API calls but better/cleaner logic separation. 129 130 * Q: Where do we want to store pending states for oneshot transactions in the client or the backend database? 131 132 * In the client makes things simpler for the backend but is incompatible with coarse-grained authorization. 133 134 * Q: Do we need coarse-grained authorization or fine-grained is enough? 135 136 * Coarse-grained authorization requires that we store pending states for operations even for the ones that are currently oneshot. We could use a different strategy for each kind.