diff options
Diffstat (limited to 'core/api-common.rst')
| -rw-r--r-- | core/api-common.rst | 243 |
1 files changed, 221 insertions, 22 deletions
diff --git a/core/api-common.rst b/core/api-common.rst index ab7726a1..521b2fc0 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -18,10 +18,14 @@ .. _http-common: -================================= -Common Taler HTTP API Conventions -================================= +.. _foo_bar: +================================== +Conventions for Taler RESTful APIs +================================== + +.. contents:: Table of Contents + :local: ------------------------- HTTP Request and Response @@ -69,6 +73,8 @@ handle the error as if an internal error (500) had been returned. requests. :http:statuscode:`400 Bad request`: One of the arguments to the request is missing or malformed. + :http:statuscode:`415 Unsupported Media Type`: + The Content-Type header was not set, or it was set to an unsupported MIME type. :http:statuscode:`500 Internal server error`: This always indicates some serious internal operational error of the exchange, such as a program bug, database problems, etc., and must not be used for @@ -186,6 +192,29 @@ Examples: to decide whether it will talk to the service. +.. _error-codes: + +----------- +Error Codes +----------- + +All error codes used in GNU Taler are defined in +`GANA <https://git.gnunet.org/gana.git/tree/gnu-taler-error-codes/>`__. + +This centralized registry also contains generators that create enumerations +and mappings from error codes to HTTP status codes and human-readable error +messages for various programming languages. + +All error codes have numeric values below 100 or above 1000, so as to never be +confused with HTTP status codes. A value of 0 is reserved for "no error" or +"success". + +In C, the respective enumeration is the ``enum TALER_ErrorCode``. + +Developers may have to re-run ``bootstrap`` and/or update their Git +submodules to ensure that they have the lastest GANA registry. + + .. _encodings-ref: ---------------- @@ -212,6 +241,7 @@ resulting encoding. Hash codes ^^^^^^^^^^ + Hash codes are strings representing base32 encoding of the respective hashed data. See `base32`_. @@ -278,6 +308,17 @@ Large numbers Large numbers such as RSA blinding factors and 256 bit keys, are transmitted as other binary data in Crockford Base32 encoding. +Decimal numbers +^^^^^^^^^^^^^^^ + +.. + FIXME: explain the representation with strings. + +.. ts:def:: DecimalNumber + + // Number with at most 8 fractional digits. + type DecimalNumber = string; + Timestamps ^^^^^^^^^^ @@ -313,6 +354,14 @@ Integers // JavaScript numbers restricted to integers. type Integer = number; +Floats +^^^^^^ + +.. ts:def:: Float + + // JavaScript numbers. + type Float = number; + Ages ^^^^ @@ -352,6 +401,76 @@ Objects // JavaScript objects, no further restrictions. type Object = object; + +Contact details +^^^^^^^^^^^^^^^ + +.. ts:def:: EmailAddress + + type EmailAddress = string; + +.. ts:def:: PhoneNumber + + type PhoneNumber = string; + +Phone numbers should start with the ``+`` symbol and the country code. + +Permissions +^^^^^^^^^^^ + +This type epresses which permissions for a subject +apply on a resource. + +.. ts:def:: LibeufinPermission + + interface LibeufinPermission { + subjectType: string; + subjectId: string; + resourceType: string; + resourceId: string; + permissionName: string + } + + +Fetch params +^^^^^^^^^^^^ + +.. _fetch-params: + +.. ts:def:: FetchParams + + interface FetchParams { + + // Because transactions are delivered by banks in "batches", + // then every batch can have different qualities. This value + // lets the request specify which type of batch ought to be + // returned. Currently, the following two type are supported: + // + // 'report': typically includes only non booked transactions. + // 'statement': typically includes only booked transactions. + level: "report" | "statement" | "all"; + + // This type indicates the time range of the query. + // It allows the following values: + // + // 'latest': retrieves the last transactions from the bank. + // If there are older unread transactions, those will *not* + // be downloaded. + // + // 'all': retrieves all the transactions from the bank, + // until the oldest. + // + // 'previous-days': currently *not* implemented, it will allow + // the request to download transactions from + // today until N days before. + // + // 'since-last': retrieves all the transactions since the last + // time one was downloaded. + // + rangeType: "latest" | "all" | "previous-days" | "since-last"; + }; + + Keys ^^^^ @@ -434,7 +553,7 @@ Blinded coin // coin's `public EdDSA key <eddsa-coin-pub>`. interface RSACoinEnvelope { cipher: "RSA" | "RSA+age_restricted"; - rsa_blinded_planchet: string; // Crockford `Base32` encoded + rsa_blinded_planchet: BlindedRsaSignature; } .. ts:def:: CSCoinEnvelope @@ -458,6 +577,25 @@ Blinded coin type DenominationBlindingKeyP = string; +. _unblinded-coin: + +Unblinded coin +^^^^^^^^^^^^^^ + +.. ts:def:: UnblindedSignature + + // The type of a coin's unblinded signature depends on the cipher that was used + // for signing with a denomination key. + // Note that for now, only RSA is supported. + type UnblindedSignature = RsaUnblindedSignature; + +.. ts:def:: RsaUnblindedSignature + + interface RsaUnblindedSignature { + cipher: "RSA"; + rsa_signature: RsaSignature; + } + .. _signature: @@ -527,6 +665,12 @@ The following constrains apply for a valid amount: An amount that is prefixed with a ``+`` or ``-`` character is also used in certain contexts. When no sign is present, the amount is assumed to be positive. +.. note:: + + In some setups, when Libeufin-Bank offers cashouts towards traditional + currencies like EUR for example, the fractional part gets restricted + to at most 2 digits. + .. ts:def:: SignedAmount type SignedAmount = string; @@ -672,6 +816,13 @@ uses 512-bit hash codes (64 bytes). struct GNUNET_HashCode hash; }; +.. sourcecode:: c + + struct TALER_OutputCommitmentHash { + struct GNUNET_HashCode hash; + }; + + .. _TALER_EcdhEphemeralPublicKeyP: .. sourcecode:: c @@ -823,10 +974,19 @@ uses 512-bit hash codes (64 bytes). uint8_t enc[sizeof (struct TALER_LinkSecretP)]; }; +.. _eddsa-token-pub: +.. sourcecode:: c + + union TALER_TokenPublicKeyP { + uint8_t eddsa_pub[32]; + uint8_t ecdhe_pub[32]; + }; + .. _Signatures: Signatures ^^^^^^^^^^ + Any piece of signed data, complies to the abstract data structure given below. .. sourcecode:: c @@ -841,9 +1001,11 @@ Any piece of signed data, complies to the abstract data structure given below. /*From gnunet_crypto_lib.h*/ struct GNUNET_CRYPTO_EccSignaturePurpose { /** - - The following constraints apply for a valid amount: - + * This field equals the number of bytes being signed, + * namely 'sizeof (struct Data)'. + */ + uint32_t size; + /** * This field is used to express the context in * which the signature is made, ensuring that a * signature cannot be lifted from one part of the protocol @@ -851,11 +1013,6 @@ Any piece of signed data, complies to the abstract data structure given below. * exchange's codebase (git://taler.net/exchange). */ uint32_t purpose; - /** - * This field equals the number of bytes being signed, - * namely 'sizeof (struct Data)'. - */ - uint32_t size; }; @@ -888,13 +1045,31 @@ within the */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct TALER_ReservePublicKeyP reserve_pub; - struct GNUNET_HashCode age_restricted_coins_commitment; - struct GNUNET_HashCode h_denoms_h; - uint8 max_age; + /** + * This is the running SHA512-hash over n*kappa + * `struct TALER_BlindedCoinHash` values + */ + struct GNUNET_HashCode h_commitment; + struct TALER_AgeMask mask; + uint8_t max_age_group; + }; + +.. _TALER_AgeWithdrawConfirmationPS: + +.. sourcecode:: c + + struct TALER_AgeWithdrawConfirmationPS { + /** + * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_AGE_WITHDRAW + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_HashCode h_commitment; + uint32_t noreveal_index; }; -.. _TALER_DepositRequestPS: +.. _taler_depositrequestps: + .. sourcecode:: c struct TALER_DepositRequestPS { @@ -912,9 +1087,15 @@ within the struct TALER_AmountNBO amount_with_fee; struct TALER_AmountNBO deposit_fee; struct TALER_MerchantPublicKeyP merchant; + struct GNUNET_HashCode wallet_data_hash; + /* @since protocol **vSUBSCRIBE** */ + struct TALER_OutputCommitmentHash h_outputs; + /* @since protocol **vSUBSCRIBE** */ + uint16_t choice_index; }; .. _TALER_DepositConfirmationPS: + .. sourcecode:: c struct TALER_DepositConfirmationPS { @@ -967,7 +1148,6 @@ within the * purpose.purpose = TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; - struct TALER_MasterPublicKeyP master_public_key; struct GNUNET_TIME_AbsoluteNBO start; struct GNUNET_TIME_AbsoluteNBO expire; struct GNUNET_TIME_AbsoluteNBO end; @@ -1015,6 +1195,9 @@ within the */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct TALER_PaytoHash h_wire_details; + struct GNUNET_HashCode h_conversion_url; + struct GNUNET_HashCode h_credit_restrictions; + struct GNUNET_HashCode h_debit_restrictions; }; .. _TALER_MasterWireFeePS: @@ -1035,7 +1218,7 @@ within the .. _TALER_GlobalFeesPS: .. sourcecode:: c - struct TALER_MasterWireFeePS { + struct TALER_GlobalFeesPS { /** * purpose.purpose = TALER_SIGNATURE_MASTER_GLOBAL_FEES */ @@ -1147,10 +1330,7 @@ within the * purpose.purpose = TALER_SIGNATURE_MERCHANT_CONTRACT */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; - struct TALER_AmountNBO total_amount; - struct TALER_AmountNBO max_fee; struct TALER_PrivateContractHash h_contract_terms; - struct TALER_MerchantPublicKeyP merchant_pub; }; .. _TALER_ConfirmWirePS: @@ -1683,6 +1863,9 @@ within the struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct GNUNET_TIME_AbsoluteNBO start_date; struct TALER_PaytoHash h_wire; + struct GNUNET_HashCode h_conversion_url; + struct GNUNET_HashCode h_credit_restrictions; + struct GNUNET_HashCode h_debit_restrictions; }; .. _TALER_MasterDelWirePS: @@ -1712,6 +1895,22 @@ within the uint32_t is_active GNUNET_PACKED; }; +.. _TALER_AmlDecisionPS: +.. sourcecode:: c + + struct TALER_AmlDecisionPS { + /** + * purpose.purpose =TALER_SIGNATURE_AML_DECISION. + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_HashCode h_justification GNUNET_PACKED; + struct GNUNET_TIME_TimestampNBO decision_time; + struct TALER_AmountNBO new_threshold; + struct TALER_PaytoHashP h_payto GNUNET_PACKED; + struct GNUNET_HashCode h_kyc_requirements; + uint32_t new_state GNUNET_PACKED; + }; + .. _TALER_PartnerConfigurationPS: .. sourcecode:: c @@ -1778,4 +1977,4 @@ within the struct GNUNET_TIME_TimestampNBO expiration_time; struct TALER_ReservePublicKeyP reserve_pub; struct GNUNET_HashCode h_attributes; - }; + }; |