diff options
Diffstat (limited to 'src/include/taler_json_lib.h')
| -rw-r--r-- | src/include/taler_json_lib.h | 444 |
1 files changed, 351 insertions, 93 deletions
diff --git a/src/include/taler_json_lib.h b/src/include/taler_json_lib.h index 102b3a6ff..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 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 @@ -29,6 +29,40 @@ #include "taler_error_codes.h" /** + * Version of this API, for compatibility tests. + */ +#define TALER_JSON_LIB_VERSION 0x00020000 + +/** + * Details about an encrypted contract. + */ +struct TALER_EncryptedContract +{ + + /** + * Signature of the client affiming this encrypted contract. + */ + struct TALER_PurseContractSignatureP econtract_sig; + + /** + * Contract decryption key for the purse. + */ + struct TALER_ContractDiffiePublicP contract_pub; + + /** + * Encrypted contract, can be NULL. + */ + void *econtract; + + /** + * Number of bytes in @e econtract. + */ + size_t econtract_size; + +}; + + +/** * Print JSON parsing related error information * @deprecated */ @@ -61,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 @@ -119,6 +141,34 @@ TALER_JSON_pack_blinded_denom_sig ( /** * Generate packer instruction for a JSON field of type + * blinded planchet. + * + * @param name name of the field to add to the object + * @param blinded_planchet blinded planchet + * @return json pack specification + */ +struct GNUNET_JSON_PackSpec +TALER_JSON_pack_blinded_planchet ( + const char *name, + const struct TALER_BlindedPlanchet *blinded_planchet); + + +/** + * Generate packer instruction for a JSON field of type + * exchange withdraw values (/csr). + * + * @param name name of the field to add to the object + * @param ewv values to transmit + * @return json pack specification + */ +struct GNUNET_JSON_PackSpec +TALER_JSON_pack_exchange_withdraw_values ( + const char *name, + const struct TALER_ExchangeWithdrawValues *ewv); + + +/** + * Generate packer instruction for a JSON field of type * amount. * * @param name name of the field to add to the object @@ -132,25 +182,28 @@ TALER_JSON_pack_amount (const char *name, /** * Generate packer instruction for a JSON field of type - * amount. + * encrypted contract. * * @param name name of the field to add to the object - * @param amount valid amount to pack + * @param econtract the encrypted contract * @return json pack specification */ struct GNUNET_JSON_PackSpec -TALER_JSON_pack_amount_nbo (const char *name, - const struct TALER_AmountNBO *amount); - +TALER_JSON_pack_econtract ( + const char *name, + const struct TALER_EncryptedContract *econtract); /** - * Convert a TALER amount to a JSON object. + * Generate packer instruction for a JSON field of type age_commitment * - * @param amount the amount - * @return a json object describing the amount + * @param name name of the field to add to the object + * @param age_commitment age commitment to add + * @return json pack specification */ -json_t * -TALER_JSON_from_amount (const struct TALER_Amount *amount); +struct GNUNET_JSON_PackSpec +TALER_JSON_pack_age_commitment ( + const char *name, + const struct TALER_AgeCommitment *age_commitment); /** @@ -160,7 +213,7 @@ TALER_JSON_from_amount (const struct TALER_Amount *amount); * @return a json object describing the amount */ json_t * -TALER_JSON_from_amount_nbo (const struct TALER_AmountNBO *amount); +TALER_JSON_from_amount (const struct TALER_Amount *amount); /** @@ -180,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); /** @@ -210,19 +262,122 @@ TALER_JSON_spec_amount_any (const char *name, /** - * Provide specification to parse given JSON object to an amount - * in any currency in network byte order. + * Provide specification to parse given JSON object to an encrypted contract. * * @param name name of the amount field in the JSON - * @param[out] r_amount where the amount has to be written + * @param[out] econtract where to store the encrypted contract * @return spec for parsing an amount */ struct GNUNET_JSON_Specification -TALER_JSON_spec_amount_any_nbo (const char *name, - struct TALER_AmountNBO *r_amount); +TALER_JSON_spec_econtract (const char *name, + struct TALER_EncryptedContract *econtract); + + +/** + * Provide specification to parse a given JSON object to an age commitment. + * + * @param name name of the age commitment field in the JSON + * @param[out] age_commitment where to store the age commitment + * @return spec for parsing an age commitment + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_age_commitment (const char *name, + struct TALER_AgeCommitment *age_commitment); /** + * 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 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_otp_type (const char *name, + enum TALER_MerchantConfirmationAlgorithm *mca); + + +/** + * Generate specification to parse all fees for + * a denomination under a prefix @a pfx. + * + * @param pfx string prefix to use + * @param currency which currency to expect + * @param[out] dfs a `struct TALER_DenomFeeSet` to initialize + */ +#define TALER_JSON_SPEC_DENOM_FEES(pfx,currency,dfs) \ + TALER_JSON_spec_amount (pfx "_withdraw", (currency), &(dfs)->withdraw), \ + TALER_JSON_spec_amount (pfx "_deposit", (currency), &(dfs)->deposit), \ + TALER_JSON_spec_amount (pfx "_refresh", (currency), &(dfs)->refresh), \ + TALER_JSON_spec_amount (pfx "_refund", (currency), &(dfs)->refund) + + +/** + * Macro to pack all of a denominations' fees under + * a given @a pfx. + * + * @param pfx string prefix to use + * @param dfs a `struct TALER_DenomFeeSet` to pack + */ +#define TALER_JSON_PACK_DENOM_FEES(pfx, dfs) \ + TALER_JSON_pack_amount (pfx "_withdraw", &(dfs)->withdraw), \ + TALER_JSON_pack_amount (pfx "_deposit", &(dfs)->deposit), \ + TALER_JSON_pack_amount (pfx "_refresh", &(dfs)->refresh), \ + TALER_JSON_pack_amount (pfx "_refund", &(dfs)->refund) + + +/** + * Generate specification to parse all global fees. + * + * @param currency which currency to expect + * @param[out] gfs a `struct TALER_GlobalFeeSet` to initialize + */ +#define TALER_JSON_SPEC_GLOBAL_FEES(currency,gfs) \ + TALER_JSON_spec_amount ("history_fee", (currency), &(gfs)->history), \ + TALER_JSON_spec_amount ("account_fee", (currency), &(gfs)->account), \ + TALER_JSON_spec_amount ("purse_fee", (currency), &(gfs)->purse) + +/** + * Macro to pack all of the global fees. + * + * @param gfs a `struct TALER_GlobalFeeSet` to pack + */ +#define TALER_JSON_PACK_GLOBAL_FEES(gfs) \ + TALER_JSON_pack_amount ("history_fee", &(gfs)->history), \ + TALER_JSON_pack_amount ("account_fee", &(gfs)->account), \ + TALER_JSON_pack_amount ("purse_fee", &(gfs)->purse) + + +/** + * Generate a parser for a group of denominations. + * + * @param[in] field name of the field, maybe NULL + * @param[in] currency name of the currency + * @param[out] group denomination group information + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_denomination_group (const char *field, + const char *currency, + struct TALER_DenominationGroup *group); + +/** * Generate line in parser specification for denomination public key. * * @param field name of the field @@ -235,10 +390,116 @@ TALER_JSON_spec_denom_pub (const char *field, /** + * 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. + * + * @param field name of the field + * @param cipher which cipher type to parse for + * @param[out] pk key to fill + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_denom_pub_cipher ( + const char *field, + enum GNUNET_CRYPTO_BlindSignatureAlgorithm cipher, + struct TALER_DenominationPublicKey *pk); + + +/** * Generate line in parser specification for denomination signature. * * @param field name of the field - * @param sig the signature to initialize + * @param[out] sig the signature to initialize * @return corresponding field spec */ struct GNUNET_JSON_Specification @@ -251,7 +512,7 @@ TALER_JSON_spec_denom_sig (const char *field, * blinded denomination signature. * * @param field name of the field - * @param sig the blinded signature to initialize + * @param[out] sig the blinded signature to initialize * @return corresponding field spec */ struct GNUNET_JSON_Specification @@ -261,6 +522,33 @@ TALER_JSON_spec_blinded_denom_sig ( /** + * Generate line in parser specification for + * exchange withdraw values (/csr). + * + * @param field name of the field + * @param[out] ewv the exchange withdraw values to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_exchange_withdraw_values ( + const char *field, + struct TALER_ExchangeWithdrawValues *ewv); + + +/** + * Generate line in parser specification for a + * blinded planchet. + * + * @param field name of the field + * @param[out] blinded_planchet the blinded planchet to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_blinded_planchet (const char *field, + struct TALER_BlindedPlanchet *blinded_planchet); + + +/** * The expected field stores a possibly internationalized string. * Internationalization means that there is another field "$name_i18n" * which is an object where the keys are languages. If this is @@ -316,20 +604,22 @@ TALER_JSON_spec_i18n_str (const char *name, */ enum GNUNET_GenericReturnValue TALER_JSON_contract_hash (const json_t *json, - struct TALER_PrivateContractHash *hc); + struct TALER_PrivateContractHashP *hc); /** - * 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); /** @@ -438,34 +728,7 @@ TALER_JSON_get_error_code2 (const void *data, */ enum GNUNET_GenericReturnValue TALER_JSON_merchant_wire_signature_hash (const json_t *wire_s, - struct TALER_MerchantWireHash *hc); - - -/** - * 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); + struct TALER_MerchantWireHashP *hc); /** @@ -532,36 +795,31 @@ TALER_JSON_wire_to_payto (const json_t *wire_s); /** - * Hash @a extensions in deposits. + * Hash @a policy extensions in deposits. * - * @param extensions contract extensions to hash - * @param[out] ech where to write the extension hash + * @param policy contract policy extension to hash + * @param[out] ech where to write the policy hash */ void -TALER_deposit_extension_hash (const json_t *extensions, - struct TALER_ExtensionContractHash *ech); +TALER_deposit_policy_hash (const json_t *policy, + struct TALER_ExtensionPolicyHashP *ech); /** - * Hash the @a config of an extension, given as JSON + * Hash the @a manifests of extensions, given as JSON * - * @param config configuration of the extension - * @param[out] eh where to write the extension hash + * @param manifests Manifests of the extensions + * @param[out] eh where to write the hash * @return GNUNET_OK on success, GNUNET_SYSERR on failure */ enum GNUNET_GenericReturnValue -TALER_extension_config_hash (const json_t *config, - struct TALER_ExtensionConfigHash *eh); +TALER_JSON_extensions_manifests_hash (const json_t *manifests, + struct TALER_ExtensionManifestsHashP *eh); /** - * Parses a JSON object { "extension": "age_restriction", "mask": <uint32> }. - * - * @param root is the json object - * @param[out] mask on succes, will contain the age mask - * @return #GNUNET_OK on success and #GNUNET_SYSERR on failure. + * Canonicalize a JSON input to a string according to RFC 8785. */ -enum GNUNET_GenericReturnValue -TALER_agemask_parse_json (const json_t *root, - struct TALER_AgeMask *mask); +char * +TALER_JSON_canonicalize (const json_t *input); #endif /* TALER_JSON_LIB_H_ */ |