aboutsummaryrefslogtreecommitdiff
path: root/brandt.h
blob: e97a8652c1c3fdf25b3150ddb45a7b439a5024ae (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
/* 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);


/**
 * Verify an auction description blob and parse it's fields. 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[in] description The description text in application choosen format.
 * @param[in] description_len Length of @a description 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_verify_desc (const void                  *auction_desc,
                    size_t                      auction_desc_len,
                    const void                  *description,
                    uint32_t                    description_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 an opaque data structure. It will be parsed and checked by
 * BRANDT_join().
 * @param[in] auction_desc_len The length in bytes 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,
             const void         *description,
             uint32_t           description_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.
 *
 * @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 a an opaque data
 * structure. It will be generated by BRANDT_new() and should be distributed to
 * all possibly interested bidders.
 * @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 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,
            const void                  *description,
            uint32_t                    description_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 */