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
281
282
283
|
/*
Unix SMB/CIFS implementation.
DATA BLOB
Copyright (C) Andrew Tridgell 2001
Copyright (C) Andrew Bartlett 2001
This program 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.
This program 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 this program. If not, see <http://www.gnu.org/licenses/>.
*/
/* This is a public header file that is installed as part of Samba.
* If you remove any functions or change their signature, update
* the so version number. */
#ifndef _SAMBA_DATABLOB_H_
#define _SAMBA_DATABLOB_H_
#ifndef _PUBLIC_
#define _PUBLIC_
#endif
#include <talloc.h>
#include <stdbool.h>
#include <stdint.h>
#include "lib/util/talloc_keep_secret.h"
/**
* @defgroup data_blob The data_blob API
* @brief The defines the data_blob API and provides function working with it.
*
* @{
*/
/* used to hold an arbitrary blob of data */
typedef struct datablob {
uint8_t *data;
size_t length;
} DATA_BLOB;
/* by making struct ldb_val and DATA_BLOB the same, we can simplify
a fair bit of code */
#define ldb_val datablob
#ifdef DOXYGEN
/**
* @brief Construct a data blob using a new top level TALLOC_CTX.
* You can pass NULL for ptr and get a blank data blob.
* Blob must be freed with data_blob_free().
*/
DATA_BLOB data_blob(const void *ptr, size_t size);
#else
#define data_blob(ptr, size) data_blob_named(ptr, size, "DATA_BLOB: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Construct a data blob using supplied TALLOC_CTX.
* You can pass NULL for ptr and get a blank data blob.
*/
DATA_BLOB data_blob_talloc(TALLOC_CTX *mem_ctx, const void *ptr, size_t size);
#else
#define data_blob_talloc(ctx, ptr, size) data_blob_talloc_named(ctx, ptr, size, "DATA_BLOB: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Construct a data blob using supplied TALLOC_CTX.
* Data is initialized using provided blob.
*/
DATA_BLOB data_blob_dup_talloc(TALLOC_CTX *mem_ctx, DATA_BLOB blob);
#else
#define data_blob_dup_talloc(ctx, blob) data_blob_talloc_named(ctx, (blob).data, (blob).length, "DATA_BLOB: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Construct a data blob using a new top level TALLOC_CTX.
* You can pass NULL for ptr and get a blank data blob.
* Blob must be freed with data_blob_free().
*/
DATA_BLOB data_blob_named(const void *ptr, size_t size, const char *name);
#else
#define data_blob_named(ptr, size, name) \
data_blob_talloc_named(NULL, (ptr), (size), name)
#endif
/**
* @brief Construct a data blob using supplied TALLOC_CTX and using data
* supplied via ptr and length and give it an explicit talloc chunk name.
*/
/**
* @brief Construct a data blob, using data supplied pointer and length
*
* @param mem_ctx memory context, if NULL a new top level context is used
* @param p pointer to input data, you can pass NULL and get a blank data
* blob
* @param length data length
* @param name talloc chunk name
* @return the blob
*/
_PUBLIC_ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
#ifdef DOXYGEN
/**
* @brief Construct a data blob using supplied TALLOC_CTX.
* Data is initialized with zeros.
*/
DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t size);
#else
#define data_blob_talloc_zero(ctx, size) \
_data_blob_talloc_zero((ctx), (size), "DATA_BLOB: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Construct a data blob using supplied TALLOC_CTX.
* Data is initialized with zeros and zeroed out when freed.
*/
DATA_BLOB data_blob_talloc_zero_s(TALLOC_CTX *mem_ctx, size_t size);
#else
#define data_blob_talloc_zero_s(ctx, size) \
_data_blob_talloc_zero_s((ctx), (size), "DATA_BLOB: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Construct a data blob using supplied TALLOC_CTX.
* You can pass NULL for ptr and get a blank data blob.
* Data is zeroed out when freed.
*/
DATA_BLOB data_blob_talloc_s(TALLOC_CTX *mem_ctx, const void *ptr, size_t size);
#else
#define data_blob_talloc_s(ctx, ptr, size) \
_data_blob_talloc_s((ctx), (ptr), (size), "DATA_BLOB: " __location__)
#endif
#ifdef DOXYGEN
/**
* @brief Construct a data blob using supplied TALLOC_CTX.
* Data is initialized using provided blob.
* Data is zeroed out when freed.
*/
DATA_BLOB data_blob_dup_talloc_s(TALLOC_CTX *mem_ctx, DATA_BLOB blob);
#else
#define data_blob_dup_talloc_s(ctx, blob) \
_data_blob_dup_talloc_s((ctx), (blob), "DATA_BLOB: " __location__)
#endif
/**
free a data blob
**/
_PUBLIC_ void data_blob_free(DATA_BLOB *d);
/**
clear a DATA_BLOB's contents
**/
_PUBLIC_ void data_blob_clear(DATA_BLOB *d);
/**
free a data blob and clear its contents
**/
_PUBLIC_ void data_blob_clear_free(DATA_BLOB *d);
static inline DATA_BLOB _data_blob_talloc_zero(TALLOC_CTX *ctx,
size_t size,
const char *name)
{
DATA_BLOB b = data_blob_talloc_named(ctx, 0, size, name);
if (b.data != NULL) {
data_blob_clear(&b);
}
return b;
}
static inline DATA_BLOB _data_blob_talloc_s(TALLOC_CTX *ctx,
const void *p,
size_t size,
const char *name)
{
DATA_BLOB b = data_blob_talloc_named(ctx, p, size, name);
if (b.data != NULL) {
talloc_keep_secret(b.data);
}
return b;
}
static inline DATA_BLOB _data_blob_talloc_zero_s(TALLOC_CTX *ctx,
size_t size,
const char *name)
{
DATA_BLOB b = data_blob_talloc_named(ctx, 0, size, name);
if (b.data != NULL) {
data_blob_clear(&b);
talloc_keep_secret(b.data);
}
return b;
}
static inline DATA_BLOB _data_blob_dup_talloc_s(TALLOC_CTX *ctx,
DATA_BLOB blob,
const char *name)
{
DATA_BLOB b = data_blob_talloc_named(ctx, blob.data, blob.length, name);
if (b.data != NULL) {
talloc_keep_secret(b.data);
}
return b;
}
/**
check if two data blobs are equal
**/
_PUBLIC_ int data_blob_cmp(const DATA_BLOB *d1, const DATA_BLOB *d2);
/**
check if two data blobs are equal, where the time taken should not depend on the
contents of either blob.
**/
_PUBLIC_ bool data_blob_equal_const_time(const DATA_BLOB *d1, const DATA_BLOB *d2);
/**
print the data_blob as hex string
**/
_PUBLIC_ char *data_blob_hex_string_upper(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
/**
print the data_blob as hex string
**/
_PUBLIC_ char *data_blob_hex_string_lower(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
/**
useful for constructing data blobs in test suites, while
avoiding const warnings
**/
_PUBLIC_ DATA_BLOB data_blob_string_const(const char *str);
/**
useful for constructing data blobs in test suites, while
avoiding const warnings
includes the terminating null character (as opposed to data_blob_string_const)
**/
_PUBLIC_ DATA_BLOB data_blob_string_const_null(const char *str);
/**
* Create a new data blob from const data
*/
_PUBLIC_ DATA_BLOB data_blob_const(const void *p, size_t length);
/**
realloc a data_blob
**/
_PUBLIC_ bool data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length);
/**
append some data to a data blob
**/
_PUBLIC_ bool data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
const void *p, size_t length);
/**
pad the length of a data blob to a multiple of
'pad'. 'pad' must be a power of two.
**/
_PUBLIC_ bool data_blob_pad(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
size_t pad);
#define data_blob_null ((DATA_BLOB){})
/** @} */ /* data_blob */
#endif /* _SAMBA_DATABLOB_H_ */
|
