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
|
/*
This file is part of GNUnet.
Copyright (C) 2009 GNUnet e.V.
GNUnet 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.
GNUnet 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
Affero General Public License for more details.
*/
/**
* @file fs/fs_tree.h
* @brief Merkle-tree-ish-CHK file encoding for GNUnet
* @see https://gnunet.org/encoding
* @author Krista Bennett
* @author Christian Grothoff
*
* TODO:
* - decide if this API should be made public (gnunet_fs_service.h)
* or remain "internal" (but with exported symbols?)
*/
#ifndef GNUNET_FS_TREE_H
#define GNUNET_FS_TREE_H
#include "fs_api.h"
/**
* Compute the depth of the CHK tree.
*
* @param flen file length for which to compute the depth
* @return depth of the tree, always > 0. A depth of 1 means only a DBLOCK.
*/
unsigned int
GNUNET_FS_compute_depth (uint64_t flen);
/**
* Calculate how many bytes of payload a block tree of the given
* depth MAY correspond to at most (this function ignores the fact that
* some blocks will only be present partially due to the total file
* size cutting some blocks off at the end).
*
* @param depth depth of the block. depth==0 is a DBLOCK.
* @return number of bytes of payload a subtree of this depth may correspond to
*/
uint64_t
GNUNET_FS_tree_compute_tree_size (unsigned int depth);
/**
* Compute how many bytes of data should be stored in
* the specified block.
*
* @param fsize overall file size, must be > 0.
* @param offset offset in the original data corresponding
* to the beginning of the tree induced by the block;
* must be < fsize
* @param depth depth of the node in the tree, 0 for DBLOCK
* @return number of bytes stored in this node
*/
size_t
GNUNET_FS_tree_calculate_block_size (uint64_t fsize, uint64_t offset,
unsigned int depth);
/**
* Context for an ECRS-based file encoder that computes
* the Merkle-ish-CHK tree.
*/
struct GNUNET_FS_TreeEncoder;
/**
* Function called asking for the current (encoded)
* block to be processed. After processing the
* client should either call "GNUNET_FS_tree_encode_next"
* or (on error) "GNUNET_FS_tree_encode_finish".
*
* @param cls closure
* @param chk content hash key for the block
* @param offset offset of the block
* @param depth depth of the block, 0 for DBLOCKs
* @param type type of the block (IBLOCK or DBLOCK)
* @param block the (encrypted) block
* @param block_size size of block (in bytes)
*/
typedef void (*GNUNET_FS_TreeBlockProcessor) (void *cls,
const struct ContentHashKey * chk,
uint64_t offset,
unsigned int depth,
enum GNUNET_BLOCK_Type type,
const void *block,
uint16_t block_size);
/**
* Function called with information about our
* progress in computing the tree encoding.
*
* @param cls closure
* @param offset where are we in the file
* @param pt_block plaintext of the currently processed block
* @param pt_size size of pt_block
* @param depth depth of the block in the tree, 0 for DBLOCKS
*/
typedef void (*GNUNET_FS_TreeProgressCallback) (void *cls, uint64_t offset,
const void *pt_block,
size_t pt_size,
unsigned int depth);
/**
* Initialize a tree encoder. This function will call "proc" and
* "progress" on each block in the tree. Once all blocks have been
* processed, "cont" will be scheduled. The "reader" will be called
* to obtain the (plaintext) blocks for the file. Note that this
* function will actually never call "proc"; the "proc" function must
* be triggered by calling "GNUNET_FS_tree_encoder_next" to trigger
* encryption (and calling of "proc") for each block.
*
* @param h the global FS context
* @param size overall size of the file to encode
* @param cls closure for reader, proc, progress and cont
* @param reader function to call to read plaintext data
* @param proc function to call on each encrypted block
* @param progress function to call with progress information
* @param cont function to call when done
* @return tree encoder context
*/
struct GNUNET_FS_TreeEncoder *
GNUNET_FS_tree_encoder_create (struct GNUNET_FS_Handle *h, uint64_t size,
void *cls, GNUNET_FS_DataReader reader,
GNUNET_FS_TreeBlockProcessor proc,
GNUNET_FS_TreeProgressCallback progress,
GNUNET_SCHEDULER_TaskCallback cont);
/**
* Encrypt the next block of the file (and
* call proc and progress accordingly; or
* of course "cont" if we have already completed
* encoding of the entire file).
*
* @param te tree encoder to use
*/
void
GNUNET_FS_tree_encoder_next (struct GNUNET_FS_TreeEncoder *te);
/**
* Get the resulting URI from the encoding.
*
* @param te the tree encoder to clean up
* @return uri set to the resulting URI (if encoding finished), NULL otherwise
*/
struct GNUNET_FS_Uri *
GNUNET_FS_tree_encoder_get_uri (struct GNUNET_FS_TreeEncoder *te);
/**
* Clean up a tree encoder and return information
* about possible errors.
*
* @param te the tree encoder to clean up
* @param emsg set to an error message (if an error occured
* within the tree encoder; if this function is called
* prior to completion and prior to an internal error,
* both "*emsg" will be set to NULL).
*/
void
GNUNET_FS_tree_encoder_finish (struct GNUNET_FS_TreeEncoder *te,
char **emsg);
#if 0
/* the functions below will be needed for persistence
but are not yet implemented -- FIXME... */
/**
* Get data that would be needed to resume
* the encoding later.
*
* @param te encoding to resume
* @param data set to the resume data
* @param size set to the size of the resume data
*/
void
GNUNET_FS_tree_encoder_resume_get_data (const struct GNUNET_FS_TreeEncoder *te,
void **data, size_t * size);
/**
* Reset tree encoder to point previously
* obtained for resuming.
*
* @param te encoding to resume
* @param data the resume data
* @param size the size of the resume data
*/
void
GNUNET_FS_tree_encoder_resume (struct GNUNET_FS_TreeEncoder *te,
const void *data, size_t size);
#endif
#endif
/* end of fs_tree.h */
|
