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"


#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 Represents the implementation of an extension.
 *
 * TODO: add documentation
 */
struct TALER_Extension
{
  /* simple linked list */
  struct TALER_Extension *next;

  enum TALER_Extension_Type type;
  char *name;
  bool critical;
  char *version;
  void *config;
  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);

  enum GNUNET_GenericReturnValue (*load_taler_config)(
    struct TALER_Extension *ext,
    const struct GNUNET_CONFIGURATION_Handle *cfg);
};

/**
 * Generic functions for extensions
 */

/*
 * @brief Sets the configuration of the extensions from 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_taler_config (
  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_Extension *
TALER_extensions_get_head ();

/*
 * @brief Adds an extension to the linked list of extensions.
 *
 * @param new_extension the new extension to be added
 * @return GNUNET_OK on success, GNUNET_SYSERR if the extension is invalid
 * (missing fields), GNUNET_NO if there is already an extension with that name
 * or type.
 */
enum GNUNET_GenericReturnValue
TALER_extensions_add (
  struct TALER_Extension *new_extension);

/**
 * @brief Finds and returns a supported extension by a given type.
 *
 * @param type 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);

#define TALER_extensions_is_enabled(ext) (NULL != (ext)->config)

/**
 * @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);


/*
 * 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
 */

#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 Registers the extension for age restriction to the list extensions
 */
enum GNUNET_GenericReturnValue
TALER_extension_age_restriction_register ();

/**
 * @brief Parses a string as a list of age groups.
 *
 * The string must consist of a colon-separated list of increasing integers
 * between 0 and 31.  Each entry represents the beginning of a new age group.
 * F.e. the string
 *
 *  "8:10:12:14:16:18:21"
 *
 * represents the following list of eight age groups:
 *
 * | Group |    Ages       |
 * | -----:|:------------- |
 * |    0  |  0, 1, ..., 7 |
 * |    1  |  8, 9         |
 * |    2  | 10, 11        |
 * |    3  | 12, 13        |
 * |    4  | 14, 15        |
 * |    5  | 16, 17        |
 * |    6  | 18, 19, 20    |
 * |    7  | 21, ...       |
 *
 * which is then encoded as a bit mask with the corresponding bits set:
 *
 *  31     24        16        8         0
 *  |      |         |         |         |
 *  oooooooo  oo1oo1o1  o1o1o1o1  ooooooo1
 *
 * @param groups String representation of age groups
 * @param[out] mask Mask representation for age restriction.
 * @return Error, if age groups were invalid, OK otherwise.
 */
enum GNUNET_GenericReturnValue
TALER_parse_age_group_string (
  const char *groups,
  struct TALER_AgeMask *mask);

/**
 * @brief Encodes the age mask into a string, like "8:10:12:14:16:18:21"
 *
 * @param mask Age mask
 * @return String representation of the age mask, allocated by GNUNET_malloc.
 *         Can be used as value in the TALER config.
 */
char *
TALER_age_mask_to_string (
  const struct TALER_AgeMask *mask);

/**
 * @brief Returns true when age restriction is configured and enabled.
 */
bool
TALER_extensions_age_restriction_is_enabled ();

/**
 * @brief Returns true when age restriction is configured (might not be
 * _enabled_, though).
 */
bool
TALER_extensions_age_restriction_is_configured ();

/**
 * @brief Returns the currently set age mask.  Note that even if age
 * restriction is not enabled, the age mask might be have a non-zero value.
 */
struct TALER_AgeMask
TALER_extensions_age_restriction_ageMask ();


/**
 * @brief Returns the amount of age groups defined.  0 means no age restriction
 * enabled.
 */
size_t
TALER_extensions_age_restriction_num_groups ();

/**
 * @brief Parses a JSON object { "age_groups": "a:b:...y:z" }.
 *
 * @param root is the json object
 * @param[out] mask on success, will contain the age mask
 * @return #GNUNET_OK on success and #GNUNET_SYSERR on failure.
 */
enum GNUNET_GenericReturnValue
TALER_JSON_parse_age_groups (const json_t *root,
                             struct TALER_AgeMask *mask);


/*
 * TODO: Add Peer2Peer Extension
 */

#endif