diff options
Diffstat (limited to 'src/include/taler_json_lib.h')
-rw-r--r-- | src/include/taler_json_lib.h | 248 |
1 files changed, 139 insertions, 109 deletions
diff --git a/src/include/taler_json_lib.h b/src/include/taler_json_lib.h index 7f17df030..98e565f0c 100644 --- a/src/include/taler_json_lib.h +++ b/src/include/taler_json_lib.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015, 2016, 2021, 2022 Taler Systems SA + Copyright (C) 2014-2024 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software @@ -28,6 +28,10 @@ #include "taler_util.h" #include "taler_error_codes.h" +/** + * Version of this API, for compatibility tests. + */ +#define TALER_JSON_LIB_VERSION 0x00020000 /** * Details about an encrypted contract. @@ -55,7 +59,6 @@ struct TALER_EncryptedContract */ size_t econtract_size; - }; @@ -92,18 +95,6 @@ TALER_JSON_pack_time_abs_human (const char *name, GNUNET_JSON_pack_string ("hint", TALER_ErrorCode_get_hint (ec)), \ GNUNET_JSON_pack_uint64 ("code", ec) -/** - * Generate packer instruction for a JSON field of type - * absolute time creating a human-readable timestamp. - * - * @param name name of the field to add to the object - * @param at absolute time to pack - * @return json pack specification - */ -struct GNUNET_JSON_PackSpec -TALER_JSON_pack_time_abs_nbo_human (const char *name, - struct GNUNET_TIME_AbsoluteNBO at); - /** * Generate packer instruction for a JSON field of type @@ -191,19 +182,6 @@ TALER_JSON_pack_amount (const char *name, /** * Generate packer instruction for a JSON field of type - * amount. - * - * @param name name of the field to add to the object - * @param amount valid amount to pack - * @return json pack specification - */ -struct GNUNET_JSON_PackSpec -TALER_JSON_pack_amount_nbo (const char *name, - const struct TALER_AmountNBO *amount); - - -/** - * Generate packer instruction for a JSON field of type * encrypted contract. * * @param name name of the field to add to the object @@ -239,16 +217,6 @@ TALER_JSON_from_amount (const struct TALER_Amount *amount); /** - * Convert a TALER amount to a JSON object. - * - * @param amount the amount - * @return a json object describing the amount - */ -json_t * -TALER_JSON_from_amount_nbo (const struct TALER_AmountNBO *amount); - - -/** * Provide specification to parse given JSON object to an amount. * The @a currency must be a valid pointer while the * parsing is done, a copy is not made. @@ -265,20 +233,19 @@ TALER_JSON_spec_amount (const char *name, /** - * Provide specification to parse given JSON object to an amount - * in network byte order. - * The @a currency must be a valid pointer while the - * parsing is done, a copy is not made. + * Provide specification to parse given JSON object to + * a currency specification. * * @param name name of the amount field in the JSON - * @param currency the currency the amount must be in - * @param[out] r_amount where the amount has to be written + * @param currency_code currency code to parse + * @param[out] r_cspec where the currency spec has to be written * @return spec for parsing an amount */ struct GNUNET_JSON_Specification -TALER_JSON_spec_amount_nbo (const char *name, - const char *currency, - struct TALER_AmountNBO *r_amount); +TALER_JSON_spec_currency_specification ( + const char *name, + const char *currency_code, + struct TALER_CurrencySpecification *r_cspec); /** @@ -317,17 +284,33 @@ struct GNUNET_JSON_Specification TALER_JSON_spec_age_commitment (const char *name, struct TALER_AgeCommitment *age_commitment); + /** - * Provide specification to parse given JSON object to an amount - * in any currency in network byte order. + * Provide specification to parse an OTP key. + * An OTP key must be an RFC 3548 base32-encoded + * value (so NOT our usual Crockford-base32 encoding!). * - * @param name name of the amount field in the JSON - * @param[out] r_amount where the amount has to be written - * @return spec for parsing an amount + * @param name name of the OTP key field in the JSON + * @param[out] otp_key where to store the OTP key + * @return spec for parsing an age commitment + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_otp_key (const char *name, + const char **otp_key); + + +/** + * Provide specification to parse an OTP method type. + * The value could be provided as an integer or + * as a descriptive string. + * + * @param name name of the OTP method type in the JSON + * @param[out] mca where to store the method type + * @return spec for parsing an age commitment */ struct GNUNET_JSON_Specification -TALER_JSON_spec_amount_any_nbo (const char *name, - struct TALER_AmountNBO *r_amount); +TALER_JSON_spec_otp_type (const char *name, + enum TALER_MerchantConfirmationAlgorithm *mca); /** @@ -380,26 +363,6 @@ TALER_JSON_spec_amount_any_nbo (const char *name, TALER_JSON_pack_amount ("account_fee", &(gfs)->account), \ TALER_JSON_pack_amount ("purse_fee", &(gfs)->purse) -/** - * Group of Denominations. These are the common fields of an array of - * denominations. - * - * The corresponding JSON-blob will also contain an array of particular - * denominations with only the timestamps, cipher-specific public key and the - * master signature. - * - **/ -struct TALER_DenominationGroup -{ - enum TALER_DenominationCipher cipher; - struct TALER_Amount value; - struct TALER_DenomFeeSet fees; - struct TALER_AgeMask age_mask; - - // hash is/should be the XOR of all SHA-512 hashes of the public keys in this - // group - struct GNUNET_HashCode hash; -}; /** * Generate a parser for a group of denominations. @@ -425,6 +388,97 @@ struct GNUNET_JSON_Specification TALER_JSON_spec_denom_pub (const char *field, struct TALER_DenominationPublicKey *pk); + +/** + * Generate line in parser specification for error codes. + * + * @param field name of the field + * @param[out] ec error code to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_ec (const char *field, + enum TALER_ErrorCode *ec); + + +/** + * Generate line in parser specification for + * HTTP/HTTPS URLs. + * + * @param field name of the field + * @param[out] url web URL to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_web_url (const char *field, + const char **url); + + +/** + * Generate line in parser specification for + * "payto://" URIs. + * + * @param field name of the field + * @param[out] payto_uri RFC 8905 URI to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_payto_uri (const char *field, + const char **payto_uri); + + +/** + * Generate line in parser specification for AML decision states. + * + * @param field name of the field + * @param[out] aml_state AML state to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_aml_decision (const char *field, + enum TALER_AmlDecisionState *aml_state); + + +/** + * Representation of a protocol version. + */ +struct TALER_JSON_ProtocolVersion +{ + /** + * Current version of the protocol. + */ + unsigned int current; + + /** + * Implementation revision for the @e current + * version. + */ + unsigned int revision; + + /** + * Number of protocol versions this @e revision is + * backwards-compatible with. Subtract this number + * from @e current to get the minimum protocol version + * required from the client. + */ + unsigned int age; +}; + + +/** + * Generate line in parser specification for protocol + * versions (``/config``). The field must be a string + * encoding the version as "$CURRENT:$REVISION:$AGE". + * + * @param field name of the field (usually "version") + * @param[out] ver protocol versions to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_version (const char *field, + struct TALER_JSON_ProtocolVersion *ver); + + /** * Generate a parser specification for a denomination public key of a given * cipher. @@ -435,9 +489,10 @@ TALER_JSON_spec_denom_pub (const char *field, * @return corresponding field spec */ struct GNUNET_JSON_Specification -TALER_JSON_spec_denom_pub_cipher (const char *field, - const enum TALER_DenominationCipher cipher, - struct TALER_DenominationPublicKey *pk); +TALER_JSON_spec_denom_pub_cipher ( + const char *field, + enum GNUNET_CRYPTO_BlindSignatureAlgorithm cipher, + struct TALER_DenominationPublicKey *pk); /** @@ -553,16 +608,18 @@ TALER_JSON_contract_hash (const json_t *json, /** - * Take a given contract with "forgettable" fields marked - * but with 'True' instead of a real salt. Replaces all - * 'True' values with proper random salts. Fails if any - * forgettable markers are neither 'True' nor valid salts. + * Take a given @a contract with "forgettable" fields marked in the @a spec + * with 'True' instead of a real salt. Replaces all 'True' values with proper + * random salts in the actual @a contract. Fails if any forgettable markers + * are neither 'True' nor valid salts. * - * @param[in,out] json JSON to transform + * @param spec specification with forgettable fields + * @param[in,out] contract JSON contract to transform * @return #GNUNET_OK on success */ enum GNUNET_GenericReturnValue -TALER_JSON_contract_seed_forgettable (json_t *json); +TALER_JSON_contract_seed_forgettable (const json_t *spec, + json_t *contract); /** @@ -675,33 +732,6 @@ TALER_JSON_merchant_wire_signature_hash (const json_t *wire_s, /** - * Check the signature in @a wire_s. Also performs rudimentary - * checks on the account data *if* supported. - * - * @param wire_s signed wire information of an exchange - * @param master_pub master public key of the exchange - * @return #GNUNET_OK if signature is valid - */ -enum GNUNET_GenericReturnValue -TALER_JSON_exchange_wire_signature_check ( - const json_t *wire_s, - const struct TALER_MasterPublicKeyP *master_pub); - - -/** - * Create a signed wire statement for the given account. - * - * @param payto_uri account specification - * @param master_priv private key to sign with - * @return NULL if @a payto_uri is malformed - */ -json_t * -TALER_JSON_exchange_wire_signature_make ( - const char *payto_uri, - const struct TALER_MasterPrivateKeyP *master_priv); - - -/** * Extract a string from @a object under the field @a field, but respecting * the Taler i18n rules and the language preferences expressed in @a * language_pattern. |