diff options
Diffstat (limited to 'src/include/taler_json_lib.h')
| -rw-r--r-- | src/include/taler_json_lib.h | 501 |
1 files changed, 362 insertions, 139 deletions
diff --git a/src/include/taler_json_lib.h b/src/include/taler_json_lib.h index 3581252ca..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 */ @@ -40,20 +74,6 @@ /** * Generate packer instruction for a JSON field of type - * absolute time. - * The absolute time value is expected to be already rounded. - * - * @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 (const char *name, - struct GNUNET_TIME_Absolute at); - - -/** - * 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 @@ -66,20 +86,6 @@ TALER_JSON_pack_time_abs_human (const char *name, /** - * Generate packer instruction for a JSON field of type - * absolute time in network byte order. - * The absolute time value is expected to be already rounded. - * - * @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 (const char *name, - struct GNUNET_TIME_AbsoluteNBO at); - - -/** * Put an error code into a JSON reply, including * both the numeric value and the hint. * @@ -89,73 +95,76 @@ TALER_JSON_pack_time_abs_nbo (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. + * denomination public key. * * @param name name of the field to add to the object - * @param at absolute time to pack + * @param pk public key * @return json pack specification */ struct GNUNET_JSON_PackSpec -TALER_JSON_pack_time_abs_nbo_human (const char *name, - struct GNUNET_TIME_AbsoluteNBO at); +TALER_JSON_pack_denom_pub ( + const char *name, + const struct TALER_DenominationPublicKey *pk); /** * Generate packer instruction for a JSON field of type - * relative time. - * The relative time value is expected to be already rounded. + * denomination signature. * * @param name name of the field to add to the object - * @param rt relative time to pack + * @param sig signature * @return json pack specification */ struct GNUNET_JSON_PackSpec -TALER_JSON_pack_time_rel (const char *name, - struct GNUNET_TIME_Relative rt); +TALER_JSON_pack_denom_sig ( + const char *name, + const struct TALER_DenominationSignature *sig); /** * Generate packer instruction for a JSON field of type - * relative time in network byte order. - * The relative time value is expected to be already rounded. + * blinded denomination signature (that needs to be + * unblinded before it becomes valid). * * @param name name of the field to add to the object - * @param rt relative time to pack + * @param sig signature * @return json pack specification */ struct GNUNET_JSON_PackSpec -TALER_JSON_pack_time_rel_nbo (const char *name, - struct GNUNET_TIME_RelativeNBO rt); +TALER_JSON_pack_blinded_denom_sig ( + const char *name, + const struct TALER_BlindedDenominationSignature *sig); /** * Generate packer instruction for a JSON field of type - * denomination public key. + * blinded planchet. * * @param name name of the field to add to the object - * @param pk public key + * @param blinded_planchet blinded planchet * @return json pack specification */ struct GNUNET_JSON_PackSpec -TALER_JSON_pack_denomination_public_key ( +TALER_JSON_pack_blinded_planchet ( const char *name, - const struct TALER_DenominationPublicKey *pk); + const struct TALER_BlindedPlanchet *blinded_planchet); /** * Generate packer instruction for a JSON field of type - * denomination signature. + * exchange withdraw values (/csr). * * @param name name of the field to add to the object - * @param sig signature + * @param ewv values to transmit * @return json pack specification */ struct GNUNET_JSON_PackSpec -TALER_JSON_pack_denomination_signature ( +TALER_JSON_pack_exchange_withdraw_values ( const char *name, - const struct TALER_DenominationSignature *sig); + const struct TALER_ExchangeWithdrawValues *ewv); /** @@ -173,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); /** @@ -201,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); /** @@ -221,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); /** @@ -251,59 +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 given JSON object to an absolute time. - * The absolute time value is expected to be already rounded. + * Provide specification to parse a given JSON object to an age commitment. * - * @param name name of the time field in the JSON - * @param[out] r_time where the time has to be written - * @return spec for parsing an absolute time + * @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_absolute_time (const char *name, - struct GNUNET_TIME_Absolute *r_time); +TALER_JSON_spec_age_commitment (const char *name, + struct TALER_AgeCommitment *age_commitment); /** - * Provide specification to parse given JSON object to an absolute time - * in network byte order. - * The absolute time value is expected to be already rounded. + * 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 time field in the JSON - * @param[out] r_time where the time has to be written - * @return spec for parsing an absolute time + * @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_absolute_time_nbo (const char *name, - struct GNUNET_TIME_AbsoluteNBO *r_time); +TALER_JSON_spec_otp_key (const char *name, + const char **otp_key); /** - * Provide specification to parse given JSON object to a relative time. - * The absolute time value is expected to be already rounded. + * 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 time field in the JSON - * @param[out] r_time where the time has to be written - * @return spec for parsing a relative time + * @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_relative_time (const char *name, - struct GNUNET_TIME_Relative *r_time); +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 @@ -311,20 +385,167 @@ TALER_JSON_spec_relative_time (const char *name, * @return corresponding field spec */ struct GNUNET_JSON_Specification -TALER_JSON_spec_denomination_public_key (const char *field, - struct TALER_DenominationPublicKey *pk); +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. + * + * @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 -TALER_JSON_spec_denomination_signature (const char *field, - struct TALER_DenominationSignature *sig); +TALER_JSON_spec_denom_sig (const char *field, + struct TALER_DenominationSignature *sig); + + +/** + * Generate line in parser specification for a + * blinded denomination signature. + * + * @param field name of the field + * @param[out] sig the blinded signature to initialize + * @return corresponding field spec + */ +struct GNUNET_JSON_Specification +TALER_JSON_spec_blinded_denom_sig ( + const char *field, + struct TALER_BlindedDenominationSignature *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); /** @@ -383,20 +604,22 @@ TALER_JSON_spec_i18n_str (const char *name, */ enum GNUNET_GenericReturnValue TALER_JSON_contract_hash (const json_t *json, - struct GNUNET_HashCode *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); /** @@ -503,36 +726,9 @@ TALER_JSON_get_error_code2 (const void *data, * @param[out] hc set to the hash * @return #GNUNET_OK on success, #GNUNET_SYSERR if @a wire_s is malformed */ -int +enum GNUNET_GenericReturnValue TALER_JSON_merchant_wire_signature_hash (const json_t *wire_s, - struct GNUNET_HashCode *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 - */ -int -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); /** @@ -598,6 +794,33 @@ char * TALER_JSON_wire_to_payto (const json_t *wire_s); +/** + * Hash @a policy extensions in deposits. + * + * @param policy contract policy extension to hash + * @param[out] ech where to write the policy hash + */ +void +TALER_deposit_policy_hash (const json_t *policy, + struct TALER_ExtensionPolicyHashP *ech); + +/** + * Hash the @a manifests of extensions, given as JSON + * + * @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_JSON_extensions_manifests_hash (const json_t *manifests, + struct TALER_ExtensionManifestsHashP *eh); + +/** + * Canonicalize a JSON input to a string according to RFC 8785. + */ +char * +TALER_JSON_canonicalize (const json_t *input); + #endif /* TALER_JSON_LIB_H_ */ /* End of taler_json_lib.h */ |