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