path: root/src/include/taler_extensions.h

/*
   This file is part of TALER
   Copyright (C) 2014-2021 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
   Foundation; either version 3, or (at your option) any later version.

   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

   You should have received a copy of the GNU General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 */
/**
 * @file include/taler_extensions.h
 * @brief Interface for extensions
 * @author Özgür Kesim
 */
#ifndef TALER_EXTENSIONS_H
#define TALER_EXTENSIONS_H

#include <gnunet/gnunet_util_lib.h>
#include "taler_crypto_lib.h"
#include "taler_json_lib.h"
#include "taler_mhd_lib.h"


#define TALER_EXTENSION_SECTION_PREFIX "exchange-extension-"

enum TALER_Extension_Type
{
  TALER_Extension_AgeRestriction = 0,
  TALER_Extension_MaxPredefined = 1 // Must be last of the predefined
};


/*
 * @brief simply linked list of extensions
 */

struct TALER_Extensions
{
  struct TALER_Extensions *next;
  const struct TALER_Extension *extension;
};

/*
 * @brief Represents the implementation of an extension.
 *
 * TODO: add documentation
 */
struct TALER_Extension
{
  enum TALER_Extension_Type type;
  char *name;
  bool critical;
  char *version;
  void *config;
  bool enabled;
  json_t *config_json;

  void (*disable)(struct TALER_Extension *ext);

  enum GNUNET_GenericReturnValue (*test_json_config)(
    const json_t *config);

  enum GNUNET_GenericReturnValue (*load_json_config)(
    struct TALER_Extension *ext,
    json_t *config);

  json_t *(*config_to_json)(
    const struct TALER_Extension *ext);

  MHD_RESULT (*http_post_handler)(
    struct MHD_Connection *connection,
    const json_t *root,
    const char *const args[]);

};

/**
 * Generic functions for extensions
 */

/*
 * @brief Loads the extensions as shared libraries, as specified in the given
 * TALER configuration.
 *
 * @param cfg Handle to the TALER configuration
 * @return GNUNET_OK on success, GNUNET_SYSERR if unknown extensions were found
 *         or any particular configuration couldn't be parsed.
 */
enum GNUNET_GenericReturnValue
TALER_extensions_load (
  const struct GNUNET_CONFIGURATION_Handle *cfg);

/*
 * @brief Checks the given obj to be a valid extension object and fill the
 * fields accordingly.
 *
 * @param[in] obj Object to verify is a valid extension
 * @param{out] critical will be set to 1 if the extension is critical according to obj
 * @param[out] version will be set to the version of the extension according to obj
 * @param[out] config will be set to the configuration of the extension according to obj
 * @return OK on success, Error otherwise
 */
enum GNUNET_GenericReturnValue
TALER_extensions_is_json_config (
  json_t *obj,
  int *critical,
  const char **version,
  json_t **config);

/*
 * @brief Sets the configuration of the extensions from a given JSON object.
 *
 * The JSON object must be of type ExchangeKeysResponse as described in
 * https://docs.taler.net/design-documents/006-extensions.html#exchange
 *
 * @param cfg JSON object containing the configuration for all extensions
 * @return #GNUNET_OK on success, #GNUNET_SYSERR if unknown extensions were
 *  found or any particular configuration couldn't be parsed.
 */
enum GNUNET_GenericReturnValue
TALER_extensions_load_json_config (
  json_t *cfg);

/*
 * @brief Returns the head of the linked list of extensions.
 */
const struct TALER_Extensions *
TALER_extensions_get_head ();

/**
 * @brief Finds and returns a supported extension by a given type.
 *
 * @param type of the extension to lookup
 * @return extension found, or NULL (should not happen!)
 */
const struct TALER_Extension *
TALER_extensions_get_by_type (
  enum TALER_Extension_Type type);


/**
 * @brief Finds and returns a supported extension by a given name.
 *
 * @param name name of the extension to lookup
 * @return the extension, if found, NULL otherwise
 */
const struct TALER_Extension *
TALER_extensions_get_by_name (
  const char *name);

/**
 * @brief Check if a given type of an extension is enabled
 *
 * @param type type of to check
 * @return true enabled, false if not enabled, will assert if type is not found.
 */
bool
TALER_extensions_is_enabled_type (
  enum TALER_Extension_Type type);

/**
 * @brief Check if an extension is enabled
 *
 * @param extension The extension handler.
 * @return true enabled, false if not enabled, will assert if type is not found.
 */
bool
TALER_extensions_is_enabled (
  const struct TALER_Extension *extension);

/*
 * Verify the signature of a given JSON object for extensions with the master
 * key of the exchange.
 *
 * The JSON object must be of type ExchangeKeysResponse as described in
 * https://docs.taler.net/design-documents/006-extensions.html#exchange
 *
 * @param extensions JSON object with the extension configuration
 * @param extensions_sig signature of the hash of the JSON object
 * @param master_pub public key to verify the signature
 * @return GNUNET_OK on success, GNUNET_SYSERR when hashing of the JSON fails
 * and GNUNET_NO if the signature couldn't be verified.
 */
enum GNUNET_GenericReturnValue
TALER_extensions_verify_json_config_signature (
  json_t *extensions,
  struct TALER_MasterSignatureP *extensions_sig,
  struct TALER_MasterPublicKeyP *master_pub);


/*
 * TALER Age Restriction Extension
 *
 * This extension is special insofar as it directly interacts with coins and
 * denominations.
 */

#define TALER_EXTENSION_SECTION_AGE_RESTRICTION (TALER_EXTENSION_SECTION_PREFIX  \
                                                 "age_restriction")

/**
 * The default age mask represents the age groups
 * 0-7, 8-9, 10-11, 12-13, 14-15, 16-17, 18-20, 21-...
 */
#define TALER_EXTENSION_AGE_RESTRICTION_DEFAULT_AGE_MASK (1 | 1 << 8 | 1 << 10 \
                                                          | 1 << 12 | 1 << 14 \
                                                          | 1 << 16 | 1 << 18 \
                                                          | 1 << 21)
#define TALER_EXTENSION_AGE_RESTRICTION_DEFAULT_AGE_GROUPS "8:10:12:14:16:18:21"


/*
 * @brief Configuration for Age Restriction
 */
struct TALER_AgeRestrictionConfig
{
  bool enabled;
  struct TALER_AgeMask mask;
  uint8_t num_groups;
};


/**
 * @brief Retrieve the age restriction configuration
 *
 * @return age restriction configuration if present, otherwise NULL.
 */
const struct TALER_AgeRestrictionConfig *
TALER_extensions_get_age_restriction_config ();

/**
 * @brief Check if age restriction is enabled
 *
 * @return true, if age restriction is loaded, configured and enabled; otherwise false.
 */
bool
TALER_extensions_is_age_restriction_enabled ();

/**
 * @brief Return the age mask for age restriction
 *
 * @return configured age mask, if age restriction is loaded, configured and enabled; otherwise zero mask.
 */
struct TALER_AgeMask
TALER_extensions_get_age_restriction_mask ();


/*
 * TODO: Add Peer2Peer Extension
 */

#endif