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
284
285
286
287
288
|
/**
* @copyright
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
* ====================================================================
* @endcopyright
*
* @file svn_checksum.h
* @brief Subversion checksum routines
*/
#ifndef SVN_CHECKSUM_H
#define SVN_CHECKSUM_H
#include <apr.h> /* for apr_size_t */
#include <apr_pools.h> /* for apr_pool_t */
#include "svn_types.h" /* for svn_boolean_t, svn_error_t */
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
* Various types of checksums.
*
* @since New in 1.6.
*/
typedef enum svn_checksum_kind_t
{
/** The checksum is (or should be set to) an MD5 checksum. */
svn_checksum_md5,
/** The checksum is (or should be set to) a SHA1 checksum. */
svn_checksum_sha1,
/** The checksum is (or should be set to) a FNV-1a 32 bit checksum,
* in big endian byte order.
* @since New in 1.9. */
svn_checksum_fnv1a_32,
/** The checksum is (or should be set to) a modified FNV-1a 32 bit,
* in big endian byte order.
* @since New in 1.9. */
svn_checksum_fnv1a_32x4
} svn_checksum_kind_t;
/**
* A generic checksum representation.
*
* @since New in 1.6.
*/
typedef struct svn_checksum_t
{
/** The bytes of the checksum. */
const unsigned char *digest;
/** The type of the checksum. This should never be changed by consumers
of the APIs. */
svn_checksum_kind_t kind;
} svn_checksum_t;
/**
* Opaque type for creating checksums of data.
*/
typedef struct svn_checksum_ctx_t svn_checksum_ctx_t;
/** Return a new checksum structure of type @a kind, initialized to the all-
* zeros value, allocated in @a pool.
*
* @since New in 1.6.
*/
svn_checksum_t *
svn_checksum_create(svn_checksum_kind_t kind,
apr_pool_t *pool);
/** Set @a checksum->digest to all zeros, which, by convention, matches
* all other checksums.
*
* @since New in 1.6.
*/
svn_error_t *
svn_checksum_clear(svn_checksum_t *checksum);
/** Compare checksums @a checksum1 and @a checksum2. If their kinds do not
* match or if neither is all zeros, and their content does not match, then
* return FALSE; else return TRUE.
*
* @since New in 1.6.
*/
svn_boolean_t
svn_checksum_match(const svn_checksum_t *checksum1,
const svn_checksum_t *checksum2);
/**
* Return a deep copy of @a checksum, allocated in @a pool. If @a
* checksum is NULL then NULL is returned.
*
* @since New in 1.6.
*/
svn_checksum_t *
svn_checksum_dup(const svn_checksum_t *checksum,
apr_pool_t *pool);
/** Return the hex representation of @a checksum, allocating the string
* in @a pool.
*
* @since New in 1.6.
*/
const char *
svn_checksum_to_cstring_display(const svn_checksum_t *checksum,
apr_pool_t *pool);
/** Return the hex representation of @a checksum, allocating the
* string in @a pool. If @a checksum->digest is all zeros (that is,
* 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL
* and NULL will be returned in that case.
*
* @since New in 1.6.
* @note Passing NULL for @a checksum in 1.6 will cause a segfault.
*/
const char *
svn_checksum_to_cstring(const svn_checksum_t *checksum,
apr_pool_t *pool);
/** Return a serialized representation of @a checksum, allocated in
* @a result_pool. Temporary allocations are performed in @a scratch_pool.
*
* Note that @a checksum may not be NULL.
*
* @since New in 1.7.
*/
const char *
svn_checksum_serialize(const svn_checksum_t *checksum,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/** Return @a checksum from the serialized format at @a data. The checksum
* will be allocated in @a result_pool, with any temporary allocations
* performed in @a scratch_pool.
*
* @since New in 1.7.
*/
svn_error_t *
svn_checksum_deserialize(const svn_checksum_t **checksum,
const char *data,
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
/** Parse the hex representation @a hex of a checksum of kind @a kind and
* set @a *checksum to the result, allocating in @a pool.
*
* If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum
* to @c NULL.
*
* @since New in 1.6.
*/
svn_error_t *
svn_checksum_parse_hex(svn_checksum_t **checksum,
svn_checksum_kind_t kind,
const char *hex,
apr_pool_t *pool);
/**
* Return in @a *checksum the checksum of type @a kind for the bytes beginning
* at @a data, and going for @a len. @a *checksum is allocated in @a pool.
*
* @since New in 1.6.
*/
svn_error_t *
svn_checksum(svn_checksum_t **checksum,
svn_checksum_kind_t kind,
const void *data,
apr_size_t len,
apr_pool_t *pool);
/**
* Return in @a pool a newly allocated checksum populated with the checksum
* of type @a kind for the empty string.
*
* @since New in 1.6.
*/
svn_checksum_t *
svn_checksum_empty_checksum(svn_checksum_kind_t kind,
apr_pool_t *pool);
/**
* Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for
* calculating checksums of type @a kind. @see svn_checksum_final()
*
* @since New in 1.6.
*/
svn_checksum_ctx_t *
svn_checksum_ctx_create(svn_checksum_kind_t kind,
apr_pool_t *pool);
/**
* Update the checksum represented by @a ctx, with @a len bytes starting at
* @a data.
*
* @since New in 1.6.
*/
svn_error_t *
svn_checksum_update(svn_checksum_ctx_t *ctx,
const void *data,
apr_size_t len);
/**
* Finalize the checksum used when creating @a ctx, and put the resultant
* checksum in @a *checksum, allocated in @a pool.
*
* @since New in 1.6.
*/
svn_error_t *
svn_checksum_final(svn_checksum_t **checksum,
const svn_checksum_ctx_t *ctx,
apr_pool_t *pool);
/**
* Return the digest size of @a checksum.
*
* @since New in 1.6.
*/
apr_size_t
svn_checksum_size(const svn_checksum_t *checksum);
/**
* Return @c TRUE iff @a checksum matches the checksum for the empty
* string.
*
* @since New in 1.8.
*/
svn_boolean_t
svn_checksum_is_empty_checksum(svn_checksum_t *checksum);
/**
* Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and
* @a expected checksums which do not match. Use @a fmt, and the following
* parameters to populate the error message.
*
* @note This function does not actually check for the mismatch, it just
* constructs the error.
*
* @a scratch_pool is used for temporary allocations; the returned error
* will be allocated in its own pool (as is typical).
*
* @since New in 1.7.
*/
svn_error_t *
svn_checksum_mismatch_err(const svn_checksum_t *expected,
const svn_checksum_t *actual,
apr_pool_t *scratch_pool,
const char *fmt,
...)
__attribute__ ((format(printf, 4, 5)));
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* SVN_CHECKSUM_H */
|