diff options
Diffstat (limited to 'core/api-common.rst')
| -rw-r--r-- | core/api-common.rst | 433 |
1 files changed, 407 insertions, 26 deletions
diff --git a/core/api-common.rst b/core/api-common.rst index 848d580d..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 @@ -117,7 +123,7 @@ handle the error as if an internal error (500) had been returned. // Name of the object that was bogus (if applicable). object?: string; - // Name of the currency than was problematic (if applicable). + // Name of the currency that was problematic (if applicable). currency?: string; // Expected type (if applicable). @@ -125,6 +131,9 @@ handle the error as if an internal error (500) had been returned. // Type that was provided instead (if applicable). type_actual?: string; + + // Extra information that doesn't fit into the above (if applicable). + extra?: Object; } ----------------------- @@ -183,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: ---------------- @@ -209,6 +241,7 @@ resulting encoding. Hash codes ^^^^^^^^^^ + Hash codes are strings representing base32 encoding of the respective hashed data. See `base32`_. @@ -275,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 ^^^^^^^^^^ @@ -310,6 +354,14 @@ Integers // JavaScript numbers restricted to integers. type Integer = number; +Floats +^^^^^^ + +.. ts:def:: Float + + // JavaScript numbers. + type Float = number; + Ages ^^^^ @@ -349,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 ^^^^ @@ -421,8 +543,31 @@ Blinded coin .. ts:def:: CoinEnvelope - // Blinded coin's `public EdDSA key <eddsa-coin-pub>`, `base32` encoded. - type CoinEnvelope = string; + // The type of a coin's blinded envelope depends on the cipher that is used + // for signing with a denomination key. + type CoinEnvelope = RSACoinEnvelope | CSCoinEnvelope ; + +.. ts:def:: RSACoinEnvelope + + // For denomination signatures based on RSA, the planchet is just a blinded + // coin's `public EdDSA key <eddsa-coin-pub>`. + interface RSACoinEnvelope { + cipher: "RSA" | "RSA+age_restricted"; + rsa_blinded_planchet: BlindedRsaSignature; + } + +.. ts:def:: CSCoinEnvelope + + // For denomination signatures based on Blind Clause-Schnorr, the planchet + // consists of the public nonce and two Curve25519 scalars which are two + // blinded challenges in the Blinded Clause-Schnorr signature scheme. + // See https://taler.net/papers/cs-thesis.pdf for details. + interface CSCoinEnvelope { + cipher: "CS" | "CS+age_restricted"; + cs_nonce: string; // Crockford `Base32` encoded + cs_blinded_c0: string; // Crockford `Base32` encoded + cs_blinded_c1: string; // Crockford `Base32` encoded + } .. ts:def:: DenominationBlindingKeyP @@ -432,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: @@ -501,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; @@ -616,7 +786,7 @@ uses 512-bit hash codes (64 bytes). .. sourcecode:: c - struct TALER_ExtensionContractHash { + struct TALER_ExtensionsPolicyHash { struct GNUNET_HashCode hash; }; @@ -633,6 +803,7 @@ uses 512-bit hash codes (64 bytes). struct GNUNET_ShortHashCode hash; }; +.. _BlindedCoinHash: .. sourcecode:: c struct TALER_BlindedCoinHash { @@ -645,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 @@ -690,6 +868,28 @@ uses 512-bit hash codes (64 bytes). uint8_t ecdhe_priv[32]; }; + +.. _AmlDecisionState: +.. sourcecode:: c + + enum TALER_AmlDecisionState { + NORMAL, PENDING, FROZEN + }; + +.. _AmlOfficerPublicKeyP: +.. sourcecode:: c + + struct TALER_AmlOfficerPublicKeyP { + uint8_t eddsa_pub[32]; + }; + +.. _AmlOfficerPrivateKeyP: +.. sourcecode:: c + + struct TALER_AmlOfficerPrivateKeyP { + uint8_t eddsa_priv[32]; + }; + .. _sign-key-pub: .. sourcecode:: c @@ -774,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 @@ -792,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 @@ -802,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; }; @@ -830,7 +1036,40 @@ within the struct TALER_BlindedCoinHash h_coin_envelope; }; -.. _TALER_DepositRequestPS: +.. _TALER_AgeWithdrawRequestPS: +.. sourcecode:: c + + struct TALER_AgeWithdrawRequestPS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_AGE_WITHDRAW + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_ReservePublicKeyP reserve_pub; + /** + * 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: + .. sourcecode:: c struct TALER_DepositRequestPS { @@ -840,7 +1079,7 @@ within the struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct TALER_PrivateContractHash h_contract_terms; struct TALER_AgeCommitmentHash h_age_commitment; - struct TALER_ExtensionContractHash h_extensions; + struct TALER_ExtensionsPolicyHash h_policy; struct TALER_MerchantWireHash h_wire; struct TALER_DenominationHash h_denom_pub; struct GNUNET_TIME_AbsoluteNBO timestamp; @@ -848,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 { @@ -860,7 +1105,7 @@ within the struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct TALER_PrivateContractHash h_contract_terms; struct TALER_MerchantWireHash h_wire; - struct TALER_ExtensionContractHash h_extensions; + struct TALER_ExtensionsPolicyHash h_policy; struct GNUNET_TIME_AbsoluteNBO timestamp; struct GNUNET_TIME_AbsoluteNBO refund_deadline; struct TALER_AmountNBO amount_without_fee; @@ -903,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; @@ -951,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: @@ -971,7 +1218,7 @@ within the .. _TALER_GlobalFeesPS: .. sourcecode:: c - struct TALER_MasterWireFeePS { + struct TALER_GlobalFeesPS { /** * purpose.purpose = TALER_SIGNATURE_MASTER_GLOBAL_FEES */ @@ -1083,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: @@ -1365,6 +1609,19 @@ within the }; +.. _TALER_ReserveOpenDepositSignaturePS: +.. sourcecode:: c + + struct TALER_PurseDepositSignaturePS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_OPEN_DEPOSIT + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_ReserveSignatureP reserve_sig; + struct TALER_AmountNBO coin_contribution; + }; + + .. _TALER_PurseDepositConfirmedSignaturePS: .. sourcecode:: c @@ -1410,6 +1667,30 @@ within the uint32_t min_age; }; +.. _TALER_AccountSetupRequestSignaturePS: +.. sourcecode:: c + + struct TALER_AccountSetupRequestSignaturePS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_ACCOUNT_SETUP + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_AmountNBO threshold; + }; + +.. _TALER_AccountSetupSuccessSignaturePS: +.. sourcecode:: c + + struct TALER_AccountSetupSuccessSignaturePS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_ACCOUNT_SETUP_SUCCESS + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_PaytoHash h_payto; + struct GNUNET_HashCode h_kyc; + struct GNUNET_TIME_AbsoluteNBO timestamp; + }; + .. _TALER_PurseMergeSuccessSignaturePS: .. sourcecode:: c @@ -1490,9 +1771,7 @@ within the struct GNUNET_CRYPTO_EccSignaturePurpose purpose; struct TALER_PursePublicKey purse_pub; union TALER_CoinSpendPublicKeyP coin_pub; - struct TALER_MerchantPublicKeyP merchant; - struct TALER_AmountNBO remaining_amount; - struct TALER_AmountNBO purse_fee_share; + struct TALER_AmountNBO refunded_amount; struct TALER_AmountNBO refund_fee; }; @@ -1584,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: @@ -1597,3 +1879,102 @@ within the struct GNUNET_TIME_AbsoluteNBO end_date; struct TALER_PaytoHash h_wire; }; + + +.. _TALER_MasterAmlOfficerStatusPS: +.. sourcecode:: c + + struct TALER_MasterAmlOfficerStatusPS { + /** + * purpose.purpose = TALER_SIGNATURE_MASTER_AML_KEY + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO change_date; + struct TALER_AmlOfficerPublicKeyP officer_pub; + struct GNUNET_HashCode h_officer_name GNUNET_PACKED; + 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 + + struct TALER_PartnerConfigurationPS { + /** + * purpose.purpose = TALER_SIGNATURE_MASTER_PARNTER_DETAILS + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_MasterPublicKeyP partner_pub; + struct GNUNET_TIME_TimestampNBO start_date; + struct GNUNET_TIME_TimestampNBO end_date; + struct GNUNET_TIME_RelativeNBO wad_frequency; + struct TALER_AmountNBO wad_fee; + struct GNUNET_HashCode h_url; + }; + +.. _TALER_ReserveOpenPS: +.. sourcecode:: c + + struct TALER_ReserveOpenPS { + /** + * Purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_OPEN + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct TALER_AmountNBO reserve_payment; + struct GNUNET_TIME_TimestampNBO request_timestamp; + struct GNUNET_TIME_TimestampNBO reserve_expiration; + uint32_t purse_limit; + }; + +.. _TALER_ReserveClosePS: +.. sourcecode:: c + + struct TALER_ReserveClosePS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_RESERVE_CLOSE + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO request_timestamp; + struct TALER_PaytoHashP target_account_h_payto; + }; + +.. _TALER_WalletReserveAttestRequestSignaturePS: +.. sourcecode:: c + + struct TALER_ReserveAttestRequestPS { + /** + * purpose.purpose = TALER_SIGNATURE_WALLET_ATTEST_REQUEST + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO request_timestamp; + struct GNUNET_HashCode h_details; + }; + +.. _TALER_ExchangeAttestPS: +.. sourcecode:: c + + struct TALER_ExchangeAttestPS { + /** + * purpose.purpose = TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + struct GNUNET_TIME_TimestampNBO attest_timestamp; + struct GNUNET_TIME_TimestampNBO expiration_time; + struct TALER_ReservePublicKeyP reserve_pub; + struct GNUNET_HashCode h_attributes; + }; |