diff options
Diffstat (limited to 'design-documents/045-kyc-inheritance.rst')
-rw-r--r-- | design-documents/045-kyc-inheritance.rst | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/design-documents/045-kyc-inheritance.rst b/design-documents/045-kyc-inheritance.rst new file mode 100644 index 00000000..f33e7ee3 --- /dev/null +++ b/design-documents/045-kyc-inheritance.rst @@ -0,0 +1,186 @@ +DD 45: Single-Depth Inheritance of KYC for Reserves +################################################### + +Summary +======= + +This document presents and discusses a mechanism by which a reserve A can +provide KYC attestation for another reserve B, whenever A's KYC attestation is +the result of a proper KYC-process and not inherited itself. During the +transitive attestation process, A can change the birthday for reserve B become +younger, i.e. choose a date closer to the current date than the original +birthday. + + +Motivation +========== + +There are two reasons that motivate our proposal: + +#. KYC attestation of a reserve is a must for Peer-2-Peer payments. However, + a KYC process is usually costly for the exchange and -ultimately- the + customer. When a customer has multiple long-term reserves, it should be + possible to inherit the KYC attestation from one to another. + +#. A parent should be able to provide KYC attestation for the long-term reserve + of his or her child and at the same time provide appropriate birthday + information. That way, the child can withdraw money from its reserve + + - with appropriate and evolving age-restriction always in place, + + - no further age-commitment interaction with the parent. + +With the ability to attest KYC transitively, we can reduce the cost of +ownership of long-term reserves and enable the principle of subsidiarity, +according to which parents are responsible for age-restriction settings. + + +Requirements +============ + +* none + +Proposed Solution +================= + +There are changes in the exchange and in the wallet necessary. + +Changes in the Exchange +^^^^^^^^^^^^^^^^^^^^^^^ + +A new configuration option in the TALER-configuration defines the maximum +number of attestations that a (KYC'ed) reserve can provide for other reserves. + +.. code:: none + + [kyc-legitimization-inheritance] + MAXIMUM_ATTESTATIONS = [number] + + +The database schema needs to be adjusted to incorporate + +* a boolean field ``inherited`` in the table ``kyc_attributes`` to indicate the + inheritance status + +* an integer field ``attestations`` in the table ``reserves`` to count the + number of transitive attestations performed by a reserve. + + +On the exchange we propose the following new endpoint: + + +.. http:post:: /kyc-attest/$TARGET_RESERVE_PUB + +**Request:** + +The request body must be a `KYCAttestationRequest` object. + +**Response:** + + :http:statuscode:`200 OK`: + Both, the attesting and the target reserves were known to the exchange, and the + KYC data of the attesting reserve has been successfully inherited by the + target reserve (with optionally adjusted birthday). + :http:statuscode:`403 Forbidden`: + The attesting reserve is not allowed to transitively attest another reserve. + This is because the attesting reserve either + + #. lacks KYC attestation or + + #. its KYC attestation was itself inherited or + + #. has reached the allowed maximum number of transitive attestations. + + The response comes with a standard `ErrorDetail`. + :http:statuscode:`404 Not found`: + One of the reserve keys belongs to a reserve which is unknown to the exchange. + The response comes with a standard `ErrorDetail`, containing the unknown key. + :http:statuscode:`409 Conflict`: + The birthday in the request is not acceptable, as it points to an earlier + point in time (more distant from current time) than the birthday of the + attesting reserve. + +**Details:** + +.. ts:def:: KYCAttestationRequest + + interface KYCAttestationRequest { + // An optional birthday for the target reserve. MUST be equal or younger + // (more recent to current time) than the birthday of the attesting + // reserve. + birthday?: FuzzyDateString; + + // The public key of the attesting reserve + attester_pub: EddsaPublicKey; + + // Signature of purpose + // ``TALER_SIGNATURE_WALLET_RESERVE_TRANSITIVE_KYC`` over + // a `TALER_ReserveKYCAttestationPS`. + attester_sig: EddsaSignature; + } + + +.. ts:def:: FuzzyDateString + + // A date of the form "YYYY-MM-DD","YYYY-MM-00" or "YYYY-00-00". + // "YYYY-MM-00" will be evaluated as "YYYY-MM-01" and + // "YYYY-00-00" will be evaluated as "YYYY-01-01". + type FuzzyDateString = string; + + +.. _TALER_ReserveKYCAttestationPS: +.. sourcecode:: c + + struct TALER_ReserveKYCAttestationPS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_TRANSITIVE_KYC + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_ReservePublicKeyP attester_reserve_pub; + struct TALER_ReservePublicKeyP target_reserve_pub; + /* If no birthday is set, must be all 0 */ + char birthday[sizeof("YYYY-MM-DD")]; + } + + +Changes in the Wallet +^^^^^^^^^^^^^^^^^^^^^ + +We need a workflow for the attestation of one wallet through another. + +TODO. + + +Definition of Done +================== + +For the exchange, the implementation of the configuration option and the +endpoint, and corresponding unit tests in ``src/testing`` are necessary. + + +For the wallet: TODO. + +Alternatives +============ + +* KYC for a reserve can only be provided by a full KYC legitimization process. + +Drawbacks +========= + +Other than adding code to the exchange: unknown. + +Discussion / Q&A +================ + +The proposed solution makes the principle of subsidiarity for age-restrictions +(i.e parents are responsible for setting the age-restriction) explicit in the +code. + +It also simplifies the KYC process for many situations for customers: Families +members and partners benefit from it. + +However, the proposed solution still allows for other ways to set +age-restriction in the wallet. For example, parents who do **not** have a +Taler wallet, are still able to assist their children with the settings of +age-restriction during the withdraw process. |