summaryrefslogtreecommitdiff
path: root/src/include/taler_json_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/taler_json_lib.h')
-rw-r--r--src/include/taler_json_lib.h272
1 files changed, 150 insertions, 122 deletions
diff --git a/src/include/taler_json_lib.h b/src/include/taler_json_lib.h
index d8912e52e..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);
/**
@@ -366,7 +349,6 @@ TALER_JSON_spec_amount_any_nbo (const char *name,
* @param[out] gfs a `struct TALER_GlobalFeeSet` to initialize
*/
#define TALER_JSON_SPEC_GLOBAL_FEES(currency,gfs) \
- TALER_JSON_spec_amount ("kyc_fee", (currency), &(gfs)->kyc), \
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)
@@ -377,31 +359,10 @@ TALER_JSON_spec_amount_any_nbo (const char *name,
* @param gfs a `struct TALER_GlobalFeeSet` to pack
*/
#define TALER_JSON_PACK_GLOBAL_FEES(gfs) \
- TALER_JSON_pack_amount ("kyc_fee", &(gfs)->kyc), \
TALER_JSON_pack_amount ("history_fee", &(gfs)->history), \
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.
@@ -427,19 +388,111 @@ 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.
*
* @param field name of the field
- * @parm cipher which cipher type to parse for
+ * @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,
- 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);
/**
@@ -555,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);
/**
@@ -677,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.
@@ -767,25 +795,25 @@ 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_ExtensionContractHashP *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_JSON_extensions_config_hash (const json_t *config,
- struct TALER_ExtensionConfigHashP *eh);
+TALER_JSON_extensions_manifests_hash (const json_t *manifests,
+ struct TALER_ExtensionManifestsHashP *eh);
/**
* Canonicalize a JSON input to a string according to RFC 8785.