/* 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 . */ /** * @file brandt.h * @brief This Header defines the external interface of libbrandt. * @author Markus Teich */ #ifndef _BRANDT_BRANDT_H #define _BRANDT_BRANDT_H #include #include #include /** 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] time_start The time when the auction will start. Bidders have * until then to register. * @param[in] time_round The maximum duration of each round in the protocol. * @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 */