045-kyc-inheritance.rst (6098B)
1 DD 45: Single-Depth Inheritance of KYC for Reserves 2 ################################################### 3 4 :Design status: Abandoned 5 :Implementation status: Not started 6 :DD shepherd: TBD 7 :Historical contributors: Özgür Kesim 8 :First published: 2023-07-30 9 :Last substantive change: 2023-07-31 10 11 .. warning:: 12 13 This is an abandoned historical design. It was not integrated into the 14 current protocol specifications and must not be treated as normative. 15 16 Summary 17 ======= 18 19 This document presents and discusses a mechanism by which a reserve A can 20 provide KYC attestation for another reserve B, whenever A's KYC attestation is 21 the result of a proper KYC-process and not inherited itself. During the 22 transitive attestation process, A can change the birthday for reserve B become 23 younger, i.e. choose a date closer to the current date than the original 24 birthday. 25 26 27 Motivation 28 ========== 29 30 There are two reasons that motivate our proposal: 31 32 #. KYC attestation of a reserve is a must for Peer-2-Peer payments. However, 33 a KYC process is usually costly for the exchange and -ultimately- the 34 customer. When a customer has multiple long-term reserves, it should be 35 possible to inherit the KYC attestation from one to another. 36 37 #. A parent should be able to provide KYC attestation for the long-term reserve 38 of his or her child and at the same time provide appropriate birthday 39 information. That way, the child can withdraw money from its reserve 40 41 - with appropriate and evolving age-restriction always in place, 42 43 - no further age-commitment interaction with the parent. 44 45 With the ability to attest KYC transitively, we can reduce the cost of 46 ownership of long-term reserves and enable the principle of subsidiarity, 47 according to which parents are responsible for age-restriction settings. 48 49 50 Requirements 51 ============ 52 53 * none 54 55 Proposed Solution 56 ================= 57 58 There are changes in the exchange and in the wallet necessary. 59 60 Changes in the Exchange 61 ^^^^^^^^^^^^^^^^^^^^^^^ 62 63 A new configuration option in the TALER-configuration defines the maximum 64 number of attestations that a (KYC'ed) reserve can provide for other reserves. 65 66 .. code:: none 67 68 [kyc-legitimization-inheritance] 69 MAXIMUM_ATTESTATIONS = [number] 70 71 72 The database schema needs to be adjusted to incorporate 73 74 * a boolean field ``inherited`` in the table ``kyc_attributes`` to indicate the 75 inheritance status 76 77 * an integer field ``attestations`` in the table ``reserves`` to count the 78 number of transitive attestations performed by a reserve. 79 80 81 On the exchange we propose the following new endpoint: 82 83 84 .. http:post:: /kyc-attest/$TARGET_RESERVE_PUB 85 86 **Request:** 87 88 The request body must be a `KYCAttestationRequest` object. 89 90 **Response:** 91 92 :http:statuscode:`200 OK`: 93 Both, the attesting and the target reserves were known to the exchange, and the 94 KYC data of the attesting reserve has been successfully inherited by the 95 target reserve (with optionally adjusted birthday). 96 :http:statuscode:`403 Forbidden`: 97 The attesting reserve is not allowed to transitively attest another reserve. 98 This is because the attesting reserve either 99 100 #. lacks KYC attestation or 101 102 #. its KYC attestation was itself inherited or 103 104 #. has reached the allowed maximum number of transitive attestations. 105 106 The response comes with a standard `ErrorDetail`. 107 :http:statuscode:`404 Not found`: 108 One of the reserve keys belongs to a reserve which is unknown to the exchange. 109 The response comes with a standard `ErrorDetail`, containing the unknown key. 110 :http:statuscode:`409 Conflict`: 111 The birthday in the request is not acceptable, as it points to an earlier 112 point in time (more distant from current time) than the birthday of the 113 attesting reserve. 114 115 **Details:** 116 117 .. ts:def:: KYCAttestationRequest 118 119 interface KYCAttestationRequest { 120 // An optional birthday for the target reserve. MUST be equal or younger 121 // (more recent to current time) than the birthday of the attesting 122 // reserve. 123 birthday?: FuzzyDateString; 124 125 // The public key of the attesting reserve 126 attester_pub: EddsaPublicKey; 127 128 // Signature of purpose 129 // ``TALER_SIGNATURE_WALLET_RESERVE_TRANSITIVE_KYC`` over 130 // a `TALER_ReserveKYCAttestationPS`. 131 attester_sig: EddsaSignature; 132 } 133 134 135 .. ts:def:: FuzzyDateString 136 137 // A date of the form "YYYY-MM-DD","YYYY-MM-00" or "YYYY-00-00". 138 // "YYYY-MM-00" will be evaluated as "YYYY-MM-01" and 139 // "YYYY-00-00" will be evaluated as "YYYY-01-01". 140 type FuzzyDateString = string; 141 142 143 .. _TALER_ReserveKYCAttestationPS: 144 .. sourcecode:: c 145 146 struct TALER_ReserveKYCAttestationPS { 147 /** 148 * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_TRANSITIVE_KYC 149 */ 150 struct GNUNET_CRYPTO_EccSignaturePurpose purpose; 151 struct TALER_ReservePublicKeyP attester_reserve_pub; 152 struct TALER_ReservePublicKeyP target_reserve_pub; 153 /* If no birthday is set, must be all 0 */ 154 char birthday[sizeof("YYYY-MM-DD")]; 155 } 156 157 158 Changes in the Wallet 159 ^^^^^^^^^^^^^^^^^^^^^ 160 161 We need a workflow for the attestation of one wallet through another. 162 163 TODO. 164 165 166 Definition of Done 167 ================== 168 169 * [ ] exchange configuration option and endpoint implemented 170 * [ ] exchange unit tests added in ``src/testing`` 171 * [ ] wallet support implemented 172 173 Alternatives 174 ============ 175 176 * KYC for a reserve can only be provided by a full KYC legitimization process. 177 178 Drawbacks 179 ========= 180 181 Other than adding code to the exchange: unknown. 182 183 Discussion / Q&A 184 ================ 185 186 The proposed solution makes the principle of subsidiarity for age-restrictions 187 (i.e parents are responsible for setting the age-restriction) explicit in the 188 code. 189 190 It also simplifies the KYC process for many situations for customers: Families 191 members and partners benefit from it. 192 193 However, the proposed solution still allows for other ways to set 194 age-restriction in the wallet. For example, parents who do **not** have a 195 Taler wallet, are still able to assist their children with the settings of 196 age-restriction during the withdraw process.