subversion/include/svn_checksum.h

/**
 * @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.
 */
/* ### TODO: When revving this, make it set @a *checksum to a non-NULL struct
 * ###       when @a hex is the all-zeroes checksum.  See
 * ### http://mail-archives.apache.org/mod_mbox/subversion-dev/201609.mbox/%3c00cd26ab-bdb3-67b4-ca6b-063266493874%40apache.org%3e
 */
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);

/**
 * Reset an existing checksum @a ctx to initial state.
 * @see svn_checksum_ctx_create()
 *
 * @since New in 1.10.
 */
svn_error_t *
svn_checksum_ctx_reset(svn_checksum_ctx_t *ctx);

/**
 * 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 */