1251881Speter/** 2251881Speter * @copyright 3251881Speter * ==================================================================== 4251881Speter * Licensed to the Apache Software Foundation (ASF) under one 5251881Speter * or more contributor license agreements. See the NOTICE file 6251881Speter * distributed with this work for additional information 7251881Speter * regarding copyright ownership. The ASF licenses this file 8251881Speter * to you under the Apache License, Version 2.0 (the 9251881Speter * "License"); you may not use this file except in compliance 10251881Speter * with the License. You may obtain a copy of the License at 11251881Speter * 12251881Speter * http://www.apache.org/licenses/LICENSE-2.0 13251881Speter * 14251881Speter * Unless required by applicable law or agreed to in writing, 15251881Speter * software distributed under the License is distributed on an 16251881Speter * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17251881Speter * KIND, either express or implied. See the License for the 18251881Speter * specific language governing permissions and limitations 19251881Speter * under the License. 20251881Speter * ==================================================================== 21251881Speter * @endcopyright 22251881Speter * 23251881Speter * @file svn_checksum.h 24251881Speter * @brief Subversion checksum routines 25251881Speter */ 26251881Speter 27251881Speter#ifndef SVN_CHECKSUM_H 28251881Speter#define SVN_CHECKSUM_H 29251881Speter 30251881Speter#include <apr.h> /* for apr_size_t */ 31251881Speter#include <apr_pools.h> /* for apr_pool_t */ 32251881Speter 33251881Speter#include "svn_types.h" /* for svn_boolean_t, svn_error_t */ 34251881Speter 35251881Speter#ifdef __cplusplus 36251881Speterextern "C" { 37251881Speter#endif /* __cplusplus */ 38251881Speter 39251881Speter 40251881Speter/** 41251881Speter * Various types of checksums. 42251881Speter * 43251881Speter * @since New in 1.6. 44251881Speter */ 45251881Spetertypedef enum svn_checksum_kind_t 46251881Speter{ 47251881Speter /** The checksum is (or should be set to) an MD5 checksum. */ 48251881Speter svn_checksum_md5, 49251881Speter 50251881Speter /** The checksum is (or should be set to) a SHA1 checksum. */ 51251881Speter svn_checksum_sha1 52251881Speter} svn_checksum_kind_t; 53251881Speter 54251881Speter/** 55251881Speter * A generic checksum representation. 56251881Speter * 57251881Speter * @since New in 1.6. 58251881Speter */ 59251881Spetertypedef struct svn_checksum_t 60251881Speter{ 61251881Speter /** The bytes of the checksum. */ 62251881Speter const unsigned char *digest; 63251881Speter 64251881Speter /** The type of the checksum. This should never be changed by consumers 65251881Speter of the APIs. */ 66251881Speter svn_checksum_kind_t kind; 67251881Speter} svn_checksum_t; 68251881Speter 69251881Speter/** 70251881Speter * Opaque type for creating checksums of data. 71251881Speter */ 72251881Spetertypedef struct svn_checksum_ctx_t svn_checksum_ctx_t; 73251881Speter 74251881Speter/** Return a new checksum structure of type @a kind, initialized to the all- 75251881Speter * zeros value, allocated in @a pool. 76251881Speter * 77251881Speter * @since New in 1.6. 78251881Speter */ 79251881Spetersvn_checksum_t * 80251881Spetersvn_checksum_create(svn_checksum_kind_t kind, 81251881Speter apr_pool_t *pool); 82251881Speter 83251881Speter/** Set @a checksum->digest to all zeros, which, by convention, matches 84251881Speter * all other checksums. 85251881Speter * 86251881Speter * @since New in 1.6. 87251881Speter */ 88251881Spetersvn_error_t * 89251881Spetersvn_checksum_clear(svn_checksum_t *checksum); 90251881Speter 91251881Speter/** Compare checksums @a checksum1 and @a checksum2. If their kinds do not 92251881Speter * match or if neither is all zeros, and their content does not match, then 93251881Speter * return FALSE; else return TRUE. 94251881Speter * 95251881Speter * @since New in 1.6. 96251881Speter */ 97251881Spetersvn_boolean_t 98251881Spetersvn_checksum_match(const svn_checksum_t *checksum1, 99251881Speter const svn_checksum_t *checksum2); 100251881Speter 101251881Speter 102251881Speter/** 103251881Speter * Return a deep copy of @a checksum, allocated in @a pool. If @a 104251881Speter * checksum is NULL then NULL is returned. 105251881Speter * 106251881Speter * @since New in 1.6. 107251881Speter */ 108251881Spetersvn_checksum_t * 109251881Spetersvn_checksum_dup(const svn_checksum_t *checksum, 110251881Speter apr_pool_t *pool); 111251881Speter 112251881Speter 113251881Speter/** Return the hex representation of @a checksum, allocating the string 114251881Speter * in @a pool. 115251881Speter * 116251881Speter * @since New in 1.6. 117251881Speter */ 118251881Speterconst char * 119251881Spetersvn_checksum_to_cstring_display(const svn_checksum_t *checksum, 120251881Speter apr_pool_t *pool); 121251881Speter 122251881Speter 123251881Speter/** Return the hex representation of @a checksum, allocating the 124251881Speter * string in @a pool. If @a checksum->digest is all zeros (that is, 125251881Speter * 0, not '0') then return NULL. In 1.7+, @a checksum may be NULL 126251881Speter * and NULL will be returned in that case. 127251881Speter * 128251881Speter * @since New in 1.6. 129251881Speter * @note Passing NULL for @a checksum in 1.6 will cause a segfault. 130251881Speter */ 131251881Speterconst char * 132251881Spetersvn_checksum_to_cstring(const svn_checksum_t *checksum, 133251881Speter apr_pool_t *pool); 134251881Speter 135251881Speter 136251881Speter/** Return a serialized representation of @a checksum, allocated in 137251881Speter * @a result_pool. Temporary allocations are performed in @a scratch_pool. 138251881Speter * 139251881Speter * Note that @a checksum may not be NULL. 140251881Speter * 141251881Speter * @since New in 1.7. 142251881Speter */ 143251881Speterconst char * 144251881Spetersvn_checksum_serialize(const svn_checksum_t *checksum, 145251881Speter apr_pool_t *result_pool, 146251881Speter apr_pool_t *scratch_pool); 147251881Speter 148251881Speter 149251881Speter/** Return @a checksum from the serialized format at @a data. The checksum 150251881Speter * will be allocated in @a result_pool, with any temporary allocations 151251881Speter * performed in @a scratch_pool. 152251881Speter * 153251881Speter * @since New in 1.7. 154251881Speter */ 155251881Spetersvn_error_t * 156251881Spetersvn_checksum_deserialize(const svn_checksum_t **checksum, 157251881Speter const char *data, 158251881Speter apr_pool_t *result_pool, 159251881Speter apr_pool_t *scratch_pool); 160251881Speter 161251881Speter 162251881Speter/** Parse the hex representation @a hex of a checksum of kind @a kind and 163251881Speter * set @a *checksum to the result, allocating in @a pool. 164251881Speter * 165251881Speter * If @a hex is @c NULL or is the all-zeros checksum, then set @a *checksum 166251881Speter * to @c NULL. 167251881Speter * 168251881Speter * @since New in 1.6. 169251881Speter */ 170251881Spetersvn_error_t * 171251881Spetersvn_checksum_parse_hex(svn_checksum_t **checksum, 172251881Speter svn_checksum_kind_t kind, 173251881Speter const char *hex, 174251881Speter apr_pool_t *pool); 175251881Speter 176251881Speter/** 177251881Speter * Return in @a *checksum the checksum of type @a kind for the bytes beginning 178251881Speter * at @a data, and going for @a len. @a *checksum is allocated in @a pool. 179251881Speter * 180251881Speter * @since New in 1.6. 181251881Speter */ 182251881Spetersvn_error_t * 183251881Spetersvn_checksum(svn_checksum_t **checksum, 184251881Speter svn_checksum_kind_t kind, 185251881Speter const void *data, 186251881Speter apr_size_t len, 187251881Speter apr_pool_t *pool); 188251881Speter 189251881Speter 190251881Speter/** 191251881Speter * Return in @a pool a newly allocated checksum populated with the checksum 192251881Speter * of type @a kind for the empty string. 193251881Speter * 194251881Speter * @since New in 1.6. 195251881Speter */ 196251881Spetersvn_checksum_t * 197251881Spetersvn_checksum_empty_checksum(svn_checksum_kind_t kind, 198251881Speter apr_pool_t *pool); 199251881Speter 200251881Speter 201251881Speter/** 202251881Speter * Create a new @c svn_checksum_ctx_t structure, allocated from @a pool for 203251881Speter * calculating checksums of type @a kind. @see svn_checksum_final() 204251881Speter * 205251881Speter * @since New in 1.6. 206251881Speter */ 207251881Spetersvn_checksum_ctx_t * 208251881Spetersvn_checksum_ctx_create(svn_checksum_kind_t kind, 209251881Speter apr_pool_t *pool); 210251881Speter 211251881Speter/** 212251881Speter * Update the checksum represented by @a ctx, with @a len bytes starting at 213251881Speter * @a data. 214251881Speter * 215251881Speter * @since New in 1.6. 216251881Speter */ 217251881Spetersvn_error_t * 218251881Spetersvn_checksum_update(svn_checksum_ctx_t *ctx, 219251881Speter const void *data, 220251881Speter apr_size_t len); 221251881Speter 222251881Speter 223251881Speter/** 224251881Speter * Finalize the checksum used when creating @a ctx, and put the resultant 225251881Speter * checksum in @a *checksum, allocated in @a pool. 226251881Speter * 227251881Speter * @since New in 1.6. 228251881Speter */ 229251881Spetersvn_error_t * 230251881Spetersvn_checksum_final(svn_checksum_t **checksum, 231251881Speter const svn_checksum_ctx_t *ctx, 232251881Speter apr_pool_t *pool); 233251881Speter 234251881Speter 235251881Speter/** 236251881Speter * Return the digest size of @a checksum. 237251881Speter * 238251881Speter * @since New in 1.6. 239251881Speter */ 240251881Speterapr_size_t 241251881Spetersvn_checksum_size(const svn_checksum_t *checksum); 242251881Speter 243251881Speter/** 244251881Speter * Return @c TRUE iff @a checksum matches the checksum for the empty 245251881Speter * string. 246251881Speter * 247251881Speter * @since New in 1.8. 248251881Speter */ 249251881Spetersvn_boolean_t 250251881Spetersvn_checksum_is_empty_checksum(svn_checksum_t *checksum); 251251881Speter 252251881Speter 253251881Speter/** 254251881Speter * Return an error of type #SVN_ERR_CHECKSUM_MISMATCH for @a actual and 255251881Speter * @a expected checksums which do not match. Use @a fmt, and the following 256251881Speter * parameters to populate the error message. 257251881Speter * 258251881Speter * @note This function does not actually check for the mismatch, it just 259251881Speter * constructs the error. 260251881Speter * 261251881Speter * @a scratch_pool is used for temporary allocations; the returned error 262251881Speter * will be allocated in its own pool (as is typical). 263251881Speter * 264251881Speter * @since New in 1.7. 265251881Speter */ 266251881Spetersvn_error_t * 267251881Spetersvn_checksum_mismatch_err(const svn_checksum_t *expected, 268251881Speter const svn_checksum_t *actual, 269251881Speter apr_pool_t *scratch_pool, 270251881Speter const char *fmt, 271251881Speter ...) 272251881Speter __attribute__ ((format(printf, 4, 5))); 273251881Speter 274251881Speter#ifdef __cplusplus 275251881Speter} 276251881Speter#endif /* __cplusplus */ 277251881Speter 278251881Speter#endif /* SVN_CHECKSUM_H */ 279