libbrandt/brandt.h

/* This file is part of libbrandt.
 * Copyright (C) 2016 GNUnet e.V.
 *
 * libbrandt 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 of the License, or (at your option) any later
 * version.
 *
 * libbrandt 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
 * libbrandt.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * @file brandt.h
 * @brief This Header defines the external interface of libbrandt.
 * @author Markus Teich
 */

#ifndef _BRANDT_BRANDT_H
#define _BRANDT_BRANDT_H

#include <stdint.h>
#include <unistd.h>

#include <gnunet/gnunet_util_lib.h>

/** Enumeration of all possible status reports for a single bidder */
enum BRANDT_BidderStatus {
	BRANDT_bidder_won,
};

/** opaque, defined in internals.h */
struct BRANDT_Auction;

/**
 * An array of this struct is given to the application by the BRANDT_CbResult()
 * callback. One instance represents the status of a single bidder.
 */
struct BRANDT_Result {
	/** Id of the bidder this instance refers to */
	uint16_t bidder;

	/** The price the bidder has to pay. This value is only set if the #status
	 * indicates the bidder has won. */
	uint16_t price;

	/** Status of the bidder */
	enum BRANDT_BidderStatus status;
};

/**
 * Functions of this type are called by libbrandt when the auction should be
 * started as a seller. The application has to broadcast the ordered list of all
 * bidders to the bidders and must return the amount of bidders to libbrandt.
 * After this function is called no more new bidders may be accepted by the
 * application.
 *
 * @param[in] auction_closure Closure pointer representing the respective
 * auction. This is the Pointer given to BRANDT_new().
 * @return The amount of bidders participating in the auction.
 */
typedef uint16_t
(*BRANDT_CbStart)(void *auction_closure);


/**
 * Functions of this type are called by libbrandt to broadcast messages to the
 * blackboard of a specific auction. They have to be sent using authenticated
 * encryption.
 *
 * @param[in] auction_closure Closure pointer representing the respective
 * auction. This is the Pointer given to BRANDT_join().
 * @param[in] msg The message to be broadcast to all participants of
 * @a auction_closure.
 * @param[in] msg_len The length of the message @a msg in bytes.
 * @return 0 on success, -1 on failure.
 */
typedef int
(*BRANDT_CbBroadcast)(void       *auction_closure,
                      const void *msg,
                      size_t     msg_len);


/**
 * Functions of this type are called by libbrandt to unicast messages to the
 * seller of a specific auction. They have to be sent using authenticated
 * encryption.
 *
 * @param[in] auction_closure Closure pointer representing the respective
 * auction. This is the Pointer given to BRANDT_join().
 * @param[in] msg The message to be sent to the seller of @a auction_closure.
 * @param[in] msg_len The length of the message @a msg in bytes.
 * @return 0 on success, -1 on failure.
 */
typedef int
(*BRANDT_CbUnicast)(void       *auction_closure,
                    const void *msg,
                    size_t     msg_len);


/**
 * Functions of this type are called by libbrandt to report the auction outcome
 * or malicious/erroneous participants.
 *
 * \todo: export *proof* of erroneous behaviour / outcome.
 *
 * @param[in] auction_closure Closure pointer representing the respective
 * auction. This is the Pointer given to BRANDT_join() / BRANDT_new().
 * @param[in] results An array of results for one or more bidders. Each bidder
 * will only be listed once. Misbehaving bidder results and auction completion
 * results are not mixed.
 * @param[in] results_len Amount of items in @a results.
 */
typedef void
(*BRANDT_CbResult)(void                 *auction_closure,
                   struct BRANDT_Result results[],
                   uint16_t             results_len);


void
BRANDT_init (struct GNUNET_CRYPTO_EccDlogContext *dlogctx);


/**
 * Parse an auction description data block. See BRANDT_new()
 * for an explanation of the different auction description fields.
 *
 * @param[in] auction_desc The auction description blob published by the seller.
 * @param[in] auction_desc_len Length of @a auction_desc in bytes.
 * @param[out] time_start Starting time of the auction. May be NULL.
 * @param[out] time_round Maximum round time of the auction. May be NULL.
 * @param[out] num_prices Amount of possible prices. May be NULL.
 * @param[out] m Auction mode. May be NULL.
 * @param[out] outcome_public Outcome setting. May be NULL.
 */
int
BRANDT_parse_desc (const void                  *auction_desc,
                   size_t                      auction_desc_len,
                   struct GNUNET_TIME_Absolute *time_start,
                   struct GNUNET_TIME_Relative *time_round,
                   uint16_t                    *num_prices,
                   uint16_t                    *m,
                   uint16_t                    *outcome_public);


/**
 * Join an auction described by the @a auction_desc parameter.
 *
 * @param[in] broadcast Pointer to the broadcast callback function
 * @param[in] unicast Pointer to the unicast callback function
 * @param[in] result Pointer to the result callback function
 * @param[in] auction_closure Closure pointer representing the auction. This
 * will not be touched by libbrandt itself. It is only passed to the callbacks.
 * @param[in] auction_desc The auction information data published by the seller.
 * This is opaque to the application. Its content will be parsed. The
 * application MUST check the signature on this data block before passing it to
 * libbrandt!
 * @param[in] auction_desc_len The length in byte of the @a auction_desc
 * structure.
 * @return A pointer, which should only be remembered and passed to
 * libbrandt functions when the client needs to refer to this auction. This is a
 * black-box pointer, do NOT dereference/change it or the data it points to!
 */
struct BRANDT_Auction *
BRANDT_join (BRANDT_CbResult    result,
             BRANDT_CbBroadcast broadcast,
             BRANDT_CbUnicast   unicast,
             void               *auction_closure,
             const void         *auction_desc,
             size_t             auction_desc_len,
             uint16_t           bid);


/* \todo: Distinguish handles for seller/buyers */
/* \todo: have cancellation (BRANDT_join_cancel()) */
/* \todo: provide means to extract a hash from auction data to */
/*        tie cryptographic operations to application-readable proposal */
/* \todo: have separate function to export 'out' variables */
/* \todo: might want to specify timeout? How do we deal with time? */
/* \todo: separate creating an auction from starting it; initial */
/*        setup needs more auction proposal details (hash, timeout, */
/*        bid structure), later we need to know # participants */
/**
 * Create a new auction described by the @a auction_desc parameter as seller.
 *
 * @param[in] broadcast Pointer to the broadcast callback function
 * @param[in] result Pointer to the result callback function
 * @param[in] auction_closure Closure pointer representing the auction. This
 * will not be touched by libbrandt. It is only passed to the callbacks.
 * @param[out] auction_desc The auction information data as an opaque data
 * structure. It is generated by this function and should be distributed to
 * all possibly interested bidders. The seller MUST sign this data block before
 * publishing it!
 * @param[out] auction_desc_len The length in bytes of the @a auction_desc
 * structure. Will be filled by BRANDT_new().
 * @param[in] num_prices The amount of possible valuations for the sold item(s).
 * If 0, a default of 256 will be used. \todo: what about 1, does it work with
 * second price auctions?
 * @param[in] m The mode of the auction. If 0, it will be a first price auction
 * where the winner has to pay the price of his bid. If >0 it will be a second
 * price auction selling exactly that amount of items and each winner has to pay
 * the price of the highest loosing bid. \todo: what if bidders < m?
 * @param[in] outcome_public If 1, the auction winner and price will be public
 * to all participants, if 0, this information will only be revealed to the
 * winner and the seller.
 * @return If invalid parameters are passed, NULL is returned. Else the return
 * value is a pointer, which should only be remembered and passed to
 * libbrandt functions when the client needs to refer to this auction. This is a
 * black-box pointer, do NOT dereference/change it or the data it points to!
 */
struct BRANDT_Auction *
BRANDT_new (BRANDT_CbResult             result,
            BRANDT_CbBroadcast          broadcast,
            BRANDT_CbStart              start,
            void                        *auction_closure,
            void                        **auction_desc,
            size_t                      *auction_desc_len,
            struct GNUNET_TIME_Absolute time_start,
            struct GNUNET_TIME_Relative time_round,
            uint16_t                    num_prices,
            uint16_t                    m,
            int                         outcome_public);


/**
 * This function must be called when bidding after receipt of the start
 * notification from the seller.
 *
 * @param[in] auction The pointer returned by BRANDT_join().
 * @param[in] i The index of this bidder assigned by the seller (from the start
 * announcement message).
 * @param[in] n The amount of bidders (from the start announcement message).
 */
void
BRANDT_bidder_start (struct BRANDT_Auction *auction,
                     uint16_t              i,
                     uint16_t              n);


/**
 * Clean up this auction on shutdown.
 *
 * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new().
 * \todo: implement (de)serialization */
void
BRANDT_destroy (struct BRANDT_Auction *auction);


/**
 * Receive a message related to a specific auction.
 *
 * If the message is from a future round and cannot be processed yet, it is
 * cached in RAM. It will not be stored on disc until it can be used, since the
 * messages completing the previous round should all arrive relatively soon.
 *
 * @param[in] auction The pointer returned by BRANDT_join() or BRANDT_new() from
 * which message @a msg was received.
 * @param[in] sender The id of the sender.
 * @param[in] msg The message that was received.
 * @param[in] msg_len The length in bytes of @a msg.
 */
void
BRANDT_got_message (struct BRANDT_Auction *auction,
                    uint16_t              sender,
                    const unsigned char   *msg,
                    size_t                msg_len);


/**\todo: Error handling functions? */

#endif /* ifndef _BRANDT_BRANDT_H */