f4932d94c0
The hash is not needed since the sellers application is required to sign the description and the bidders application is required to check the signature. Since the arbitrary description used by the application was only used inside this hash, it can be removed as well.
276 lines
11 KiB
C
276 lines
11 KiB
C
/* 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 */
|